# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand. overlay: 1.0.0 info: title: API Evangelist conversational phrasing for External Agents API version: 1.0.0 extends: openapi/profound-agents-api-openapi.yml actions: - target: $.info update: x-apievangelist-phrasing: method: generated generated: '2026-10-01' generator: build-phrasing.py label: Generated by API Evangelist operations: 10 - target: $.paths['/v1/agents'].get update: x-apievangelist-phrasing: intent: List the organization's agents effect: read questions: - Which agents does my organization have in Profound? - Can I see only the agents that have never been published? - What's the difference between a draft agent and a published one in my agent list? instructions: - text: List all of my organization's agents. - text: Show me only agents with status {statuses}. slots: statuses: query.statuses - text: List the next {limit} agents after cursor {next_cursor}. slots: limit: query.limit next_cursor: query.next_cursor method: generated generated: '2026-10-01' - target: $.paths['/v1/agents'].post update: x-apievangelist-phrasing: intent: Create a new draft agent effect: write questions: - How do I build a new agent from scratch for my organization? - Is a newly created agent live right away or does it start as a draft? instructions: - text: Create a draft agent called {name} in organization {organization_id}. slots: name: requestBody.name organization_id: requestBody.organization_id - text: Create agent {name} in org {organization_id} described as {description} with workflow graph {graph}. slots: name: requestBody.name organization_id: requestBody.organization_id description: requestBody.description graph: requestBody.graph method: generated generated: '2026-10-01' - target: $.paths['/v1/agents/{agent_id}/publish'].post update: x-apievangelist-phrasing: intent: Publish an agent's draft as live effect: write questions: - How do I take my agent's draft live? - Why would publishing an agent fail with a 422 validation error? instructions: - text: Publish the latest draft of agent {agent_id}. slots: agent_id: path.agent_id - text: Promote agent {agent_id}'s draft graph to a new published version. slots: agent_id: path.agent_id method: generated generated: '2026-10-01' - target: $.paths['/v1/agents/node-types'].get update: x-apievangelist-phrasing: intent: List node types for building agents effect: read questions: - What building blocks can I use when designing an agent workflow? - Which node types are available for agent graphs, and can I cache that list? instructions: - text: List every node type I can use in an agent graph. - text: Show the catalog of available agent node types. method: generated generated: '2026-10-01' - target: $.paths['/v1/agents/node-types/{node_type}/schema'].get update: x-apievangelist-phrasing: intent: Get the config schema for a node type effect: read questions: - What configuration fields does a particular agent node type accept? - How can I tell when a node type's JSON schema has changed? instructions: - text: Get the configuration JSON schema for node type {node_type}. slots: node_type: path.node_type - text: Fetch the schema and schema_version for the {node_type} node. slots: node_type: path.node_type method: generated generated: '2026-10-01' - target: $.paths['/v1/agents/{agent_id}'].get update: x-apievangelist-phrasing: intent: Get an agent's details effect: read questions: - Can I look up one agent's details and status? - Is it possible to view an agent's unpublished draft instead of its live version? instructions: - text: Show me agent {agent_id}. slots: agent_id: path.agent_id - text: Get the {version} version of agent {agent_id} with its schema details. slots: agent_id: path.agent_id version: query.version method: generated generated: '2026-10-01' - target: $.paths['/v1/agents/{agent_id}'].patch update: x-apievangelist-phrasing: intent: Replace an agent's draft graph effect: write questions: - How do I fix my agent's workflow without creating a new agent? - Does updating an agent re-validate the draft before I publish it? instructions: - text: Replace the draft graph of agent {agent_id} with {graph}. slots: agent_id: path.agent_id graph: requestBody.graph - text: Save this revised workflow {graph} as agent {agent_id}'s draft and tell me if it validates. slots: agent_id: path.agent_id graph: requestBody.graph method: generated generated: '2026-10-01' - target: $.paths['/v1/agents/{agent_id}/graph'].get update: x-apievangelist-phrasing: intent: Get an agent's workflow graph effect: read questions: - Can I export an agent's nodes and edges so I can copy it? - Who can see an agent's draft graph versus its published graph? instructions: - text: Export the nodes and edges of agent {agent_id}. slots: agent_id: path.agent_id - text: Get the {version} workflow graph for agent {agent_id} so I can edit a copy. slots: agent_id: path.agent_id version: query.version method: generated generated: '2026-10-01' - target: $.paths['/v1/agents/{agent_id}/runs'].post update: x-apievangelist-phrasing: intent: Start a run of a published agent effect: write questions: - How do I execute one of my agents? - Can I run an agent that has only a draft and was never published? instructions: - text: Run agent {agent_id} now. slots: agent_id: path.agent_id - text: Kick off a new execution of agent {agent_id}'s live version. slots: agent_id: path.agent_id method: generated generated: '2026-10-01' - target: $.paths['/v1/agents/{agent_id}/runs/{run_id}'].get update: x-apievangelist-phrasing: intent: Check an agent run's status and result effect: read questions: - Has my agent run finished, and what did it return? - Can I get verbose detail on an individual agent run? instructions: - text: Check the status of run {run_id} for agent {agent_id}. slots: agent_id: path.agent_id run_id: path.run_id - text: Get verbose={verbose} results for run {run_id} of agent {agent_id}. slots: agent_id: path.agent_id run_id: path.run_id verbose: query.verbose method: generated generated: '2026-10-01'