openapi: 3.2.0 info: title: External Agents API version: 6551bd49db665ffb7f80780b3e150b8e8b780cc3 servers: - url: https://api.tryprofound.com description: Production Server tags: - name: Agents paths: /v1/agents: get: tags: - Agents summary: List agents description: 'List agents available to your organization. Agent status reflects whether an agent has ever been published. `published` agents have a live published version. `draft` agents have not been published yet.' operationId: list_agents_v1_agents_get security: - APIKeyHeader: [] - BearerAuth: [] parameters: - name: statuses in: query required: false schema: anyOf: - type: array items: $ref: '#/components/schemas/ListAgentsStatusFilter' - type: 'null' description: Optional status filter. Use `published` to list agents that have a live published version, or `draft` to list agents that have not been published yet. Defaults to `published`. title: Statuses description: Optional status filter. Use `published` to list agents that have a live published version, or `draft` to list agents that have not been published yet. Defaults to `published`. - name: limit in: query required: false schema: type: integer maximum: 100 exclusiveMinimum: 0 default: 100 title: Limit - name: next_cursor in: query required: false schema: anyOf: - type: string - type: 'null' title: Next Cursor responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ListAgentsResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' post: tags: - Agents summary: Create an agent description: 'Create a new draft agent owned by the given organization. `organization_id` is required and you must be a member of it. The agent is created as a `draft`; publish it with `POST /v1/agents/{agent_id}/publish` once its graph is ready.' operationId: create_agent_v1_agents_post security: - APIKeyHeader: [] - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAgentRequest' description: The agent to create. responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Agent' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/publish: post: tags: - Agents summary: Publish an agent description: 'Publish an agent''s latest draft as its live published version. You must be a member of the agent''s organization. Publishing promotes the current draft graph to a new published version. A draft that cannot produce its declared input/output contract is rejected with `422` and is not published.' operationId: publish_agent_v1_agents__agent_id__publish_post security: - APIKeyHeader: [] - BearerAuth: [] parameters: - name: agent_id in: path required: true schema: type: string format: uuid description: The ID of the agent to publish. title: Agent Id description: The ID of the agent to publish. responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Agent' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/node-types: get: tags: - Agents summary: List node types description: 'List the node types available for building agents. The set is deterministic and does not depend on the caller, so the response is safe to cache across sessions. Integration-dependent and dynamic-schema node types are intentionally excluded in v1.' operationId: list_node_types_v1_agents_node_types_get responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ListNodeTypesResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] - BearerAuth: [] /v1/agents/node-types/{node_type}/schema: get: tags: - Agents summary: Get a node type schema description: 'Retrieve the JSON schema for a single node type. The `schema` field is an opaque JSON Schema for the node''s configuration. Use `schema_version` as a cache key — it bumps whenever the schema changes.' operationId: get_node_type_schema_v1_agents_node_types__node_type__schema_get security: - APIKeyHeader: [] - BearerAuth: [] parameters: - name: node_type in: path required: true schema: type: string description: The node type to fetch the schema for, e.g. `llm`. title: Node Type description: The node type to fetch the schema for, e.g. `llm`. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/NodeSchemaResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}: get: tags: - Agents summary: Get an agent description: 'Retrieve an agent and its schema details. Agents can have both a live published version and a draft version with newer unpublished changes. Use the `version` parameter to choose which state to return.' operationId: get_agent_v1_agents__agent_id__get security: - APIKeyHeader: [] - BearerAuth: [] parameters: - name: agent_id in: path required: true schema: type: string format: uuid description: The ID of the agent to retrieve. title: Agent Id description: The ID of the agent to retrieve. - name: version in: query required: false schema: $ref: '#/components/schemas/AgentVersion' description: Version of the agent to retrieve. Use `published` for the live version, or `draft` for the latest unpublished changes for the same agent. Defaults to `published`. default: published description: Version of the agent to retrieve. Use `published` for the live version, or `draft` for the latest unpublished changes for the same agent. Defaults to `published`. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AgentDetail' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' patch: tags: - Agents summary: Update an agent description: 'Update an agent''s draft graph in place. You must be a member of the agent''s organization. The agent''s draft is replaced with the supplied graph and re-validated, so you can iterate one draft — create, then update per fix — instead of creating a new agent on every change. The response carries the updated `validation`; publish with `POST /v1/agents/{agent_id}/publish` once `validation.valid`.' operationId: update_agent_v1_agents__agent_id__patch security: - APIKeyHeader: [] - BearerAuth: [] parameters: - name: agent_id in: path required: true schema: type: string format: uuid description: The ID of the agent to update. title: Agent Id description: The ID of the agent to update. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateAgentRequest' description: The new draft graph for the agent. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AgentDetail' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/graph: get: tags: - Agents summary: Get an agent's graph description: 'Retrieve an agent''s full workflow graph (`{nodes, edges}`). The graph is returned verbatim in the canonical dialect — the same shape `POST /v1/agents` and `PATCH /v1/agents/{agent_id}` accept — so a known-good agent can be read back, copied, and edited. Tool-backed nodes appear in their lowered `tool` form rather than the friendly v1 node types. A `draft` is visible only to its creator; the `published` version is visible across its organization.' operationId: get_agent_graph_v1_agents__agent_id__graph_get security: - APIKeyHeader: [] - BearerAuth: [] parameters: - name: agent_id in: path required: true schema: type: string format: uuid description: The ID of the agent whose graph to retrieve. title: Agent Id description: The ID of the agent whose graph to retrieve. - name: version in: query required: false schema: $ref: '#/components/schemas/AgentVersion' description: Version of the agent whose graph to retrieve. Use `published` for the live version, or `draft` for the latest unpublished changes. Defaults to `published`. default: published description: Version of the agent whose graph to retrieve. Use `published` for the live version, or `draft` for the latest unpublished changes. Defaults to `published`. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AgentGraph' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/runs: post: tags: - Agents summary: Run an agent description: 'Start a new run for an agent. Runs always execute the agent''s live published version, so the agent must be published first with `POST /v1/agents/{agent_id}/publish`. Unpublished drafts cannot be run.' operationId: run_agent_v1_agents__agent_id__runs_post security: - APIKeyHeader: [] - BearerAuth: [] parameters: - name: agent_id in: path required: true schema: type: string format: uuid description: The ID of the agent to run. title: Agent Id description: The ID of the agent to run. requestBody: content: application/json: schema: anyOf: - $ref: '#/components/schemas/RunAgentRequest' - type: 'null' description: Inputs to send to the agent run. title: Request responses: '202': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AcceptedAgentRun' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/runs/{run_id}: get: tags: - Agents summary: Get an agent run description: Retrieve the current status and result details for an agent run. operationId: get_agent_run_v1_agents__agent_id__runs__run_id__get security: - APIKeyHeader: [] - BearerAuth: [] parameters: - name: agent_id in: path required: true schema: type: string format: uuid description: The ID of the agent that owns the run. title: Agent Id description: The ID of the agent that owns the run. - name: run_id in: path required: true schema: type: string format: uuid description: The ID of the run to retrieve. title: Run Id description: The ID of the run to retrieve. - name: verbose in: query required: false schema: type: boolean description: Include each step's raw `outputs` payload in the execution trace. default: false title: Verbose description: Include each step's raw `outputs` payload in the execution trace. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AgentRun' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ListNodeTypesResponse: properties: data: items: $ref: '#/components/schemas/NodeTypeSummary' type: array title: Data description: Allowlisted node types, returned as thin summaries. additionalProperties: false type: object required: - data title: ListNodeTypesResponse description: List of node types available to v1 agent authors. RunAgentRequest: properties: inputs: additionalProperties: true type: object title: Inputs description: Input values for the run. Keys should match the property names defined in `schema.input`. Omit the request body when the agent does not require inputs. additionalProperties: false type: object title: RunAgentRequest description: Request body for starting an agent run. AgentRun: properties: id: type: string format: uuid title: Id description: Unique ID for the run. agent_id: type: string format: uuid title: Agent Id description: Unique ID of the agent for this run. status: $ref: '#/components/schemas/AgentRunStatus' description: Current status of the run. started_at: anyOf: - type: string format: date-time - type: 'null' title: Started At description: When the run started, if it has started. finished_at: anyOf: - type: string format: date-time - type: 'null' title: Finished At description: When the run finished, if it has completed. error: anyOf: - additionalProperties: true type: object - type: 'null' title: Error description: Error details, when the run fails and error information is available. outputs: additionalProperties: true type: object title: Outputs description: Output values returned by the run, keyed by variable ID. This object conforms to `schema.output` from the agent detail response and is empty when no outputs are available. steps: anyOf: - items: $ref: '#/components/schemas/AgentRunStep' type: array - type: 'null' title: Steps description: Ordered step-by-step execution trace — one entry per node that ran, in execution order. Always present once the run has executed a node; per-node `outputs` inside each step are included only when the request asks for `verbose`. additionalProperties: false type: object required: - id - agent_id - status title: AgentRun description: Status and result details for an agent run. AcceptedAgentRun: properties: id: type: string format: uuid title: Id description: Unique ID for the accepted run. agent_id: type: string format: uuid title: Agent Id description: Unique ID of the agent for this run. status: $ref: '#/components/schemas/AgentRunStatus' description: Initial status of the accepted run. started_at: anyOf: - type: string format: date-time - type: 'null' title: Started At description: When the run started, if execution began immediately. additionalProperties: false type: object required: - id - agent_id - status title: AcceptedAgentRun description: Run details returned after a run request is accepted. CursorPagination: properties: limit: type: integer maximum: 50000.0 exclusiveMinimum: 0.0 title: Limit description: Maximum number of results to return. Default is 10,000, maximum is 50,000. default: 10000 next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: Token for the next page, if more results are available. additionalProperties: false type: object title: CursorPagination description: Cursor-based pagination metadata. AgentGraph: properties: agent_id: type: string format: uuid title: Agent Id description: Unique ID of the agent the graph belongs to. version: $ref: '#/components/schemas/AgentVersion' description: Which version of the agent this graph is — `published` or `draft`. graph: additionalProperties: true type: object title: Graph description: 'Workflow graph (`{nodes, edges}`) in the canonical dialect — the same shape `create` and `update` accept. Treat it as an opaque object: it is returned verbatim, so tool-backed nodes appear in their lowered `tool` form rather than the friendly v1 node types. Read it back to copy and edit a known-good agent.' additionalProperties: false type: object required: - agent_id - version - graph title: AgentGraph description: An agent version's workflow graph in the canonical dialect. ListAgentsStatusFilter: type: string enum: - published - draft title: ListAgentsStatusFilter description: Statuses you can use to filter the list agents response. AgentValidationIssue: properties: code: type: string title: Code description: Stable machine-readable identifier for the kind of issue. message: type: string title: Message description: Human-readable description of the issue. node_id: anyOf: - type: string - type: 'null' title: Node Id description: ID of the node the issue applies to, if node-specific. node_title: anyOf: - type: string - type: 'null' title: Node Title description: Display title of the affected node, if available. field: anyOf: - type: string - type: 'null' title: Field description: Name of the offending field on the node, if field-specific. field_title: anyOf: - type: string - type: 'null' title: Field Title description: Display title of the affected field, if available. violation: anyOf: - type: string - type: 'null' title: Violation description: The specific constraint that was violated, if available. additionalProperties: false type: object required: - code - message title: AgentValidationIssue description: A single problem found while validating an agent's graph. ListAgentsResponse: properties: data: items: $ref: '#/components/schemas/Agent' type: array title: Data description: Agents returned for this page. pagination: $ref: '#/components/schemas/CursorPagination' description: Cursor pagination details for this response. additionalProperties: false type: object required: - data title: ListAgentsResponse description: Paginated list of agents. AgentStatus: type: string enum: - draft - published - unknown title: AgentStatus description: Current availability status for an agent. AgentSchema: properties: input: additionalProperties: true type: object title: Input description: JSON Schema for the agent's `inputs` object. Use the top-level property keys as input field names when starting a run. output: additionalProperties: true type: object title: Output description: JSON Schema for the `outputs` object returned by `GET /v1/agents/{agent_id}/runs/{run_id}`. additionalProperties: false type: object required: - input - output title: AgentSchema description: Schema metadata for an agent. AgentVersion: type: string enum: - published - draft title: AgentVersion description: Version selector for retrieving a specific agent. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError AgentDetail: properties: id: type: string format: uuid title: Id description: Unique ID for the agent. organization_id: type: string format: uuid title: Organization Id description: Unique ID of the organization that owns the agent. name: type: string title: Name description: Display name of the agent. status: $ref: '#/components/schemas/AgentStatus' description: Current status of the agent. created_at: type: string format: date-time title: Created At description: When the agent was created. description: anyOf: - type: string - type: 'null' title: Description description: Short description of the agent, if provided. schema: anyOf: - $ref: '#/components/schemas/AgentSchema' - type: 'null' description: Input and output schemas for this agent. Omitted while the agent's graph cannot be previewed (e.g. an empty or structurally-invalid draft); check `validation` to see what needs fixing. validation: anyOf: - $ref: '#/components/schemas/AgentValidation' - type: 'null' description: Validation report for the agent's graph, when available. Use `validation.valid` to check the agent is publishable. additionalProperties: false type: object required: - id - organization_id - name - status - created_at title: AgentDetail description: Detailed information for an agent. UpdateAgentRequest: properties: graph: additionalProperties: true type: object title: Graph description: New workflow graph for the agent's draft version. Replaces the current draft graph; the agent is iterated in place rather than re-created, so its ID is stable. Required — a null graph is rejected as a 422 here rather than as a relayed upstream error. additionalProperties: false type: object required: - graph title: UpdateAgentRequest description: Request body for updating a draft agent's graph in place. AgentValidation: properties: valid: type: boolean title: Valid description: Whether the agent's graph is valid and ready to publish. issues: items: $ref: '#/components/schemas/AgentValidationIssue' type: array title: Issues description: Problems found while validating the graph. Empty when `valid` is true. additionalProperties: false type: object required: - valid title: AgentValidation description: 'Result of validating an agent''s graph. Mirrors the report computed on every read, so callers can confirm a draft is publishable before calling publish.' NodeTypeSummary: properties: node_type: type: string title: Node Type description: Stable identifier for the node type, e.g. `llm`. display_name: type: string title: Display Name description: Human-readable name for the node type. description: anyOf: - type: string - type: 'null' title: Description description: Short description of what the node type does, if provided. additionalProperties: false type: object required: - node_type - display_name title: NodeTypeSummary description: Thin summary for a node type available to v1 agent authors. AgentRunStep: properties: node_id: type: string title: Node Id description: ID of the node that ran, within its agent graph. node_type: type: string title: Node Type description: Kind of node, e.g. "profound_visibility", "llm", "conditional". title: type: string title: Title description: Human-readable title of the node. status: type: string title: Status description: Terminal status of this node execution. elapsed_time: anyOf: - type: number - type: 'null' title: Elapsed Time description: Wall-clock seconds the node took, if recorded. finished_at: anyOf: - type: string format: date-time - type: 'null' title: Finished At description: When the node finished, if it has. error_message: anyOf: - type: string - type: 'null' title: Error Message description: Failure detail for this node, when it failed. outputs: anyOf: - additionalProperties: true type: object - type: 'null' title: Outputs description: Raw output payload this node produced. Included only when the request asks for `verbose`. additionalProperties: false type: object required: - node_id - node_type - title - status title: AgentRunStep description: 'One executed node in a run''s step trace, in execution order. The lightweight fields always ship; ``outputs`` is populated only when the run-retrieve request asks for ``verbose``.' NodeSchemaResponse: properties: node_type: type: string title: Node Type description: Stable identifier for the node type, e.g. `llm`. schema: additionalProperties: true type: object title: Schema description: Opaque JSON Schema for the node's configuration. Treat this as an arbitrary object; its internal shape can change between `schema_version` bumps. schema_version: type: string title: Schema Version description: Opaque version string for the node schema. Bumps whenever the underlying schema changes, so it can be used as a client-side cache key. description: anyOf: - type: string - type: 'null' title: Description description: Short description of what the node type does, if provided. examples: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' title: Examples description: 'Worked example configurations for the node type, in the canonical graph dialect. Curated authoring guidance, versioned by `docs_version` (NOT `schema_version`): they illustrate a valid shape at curation time but are a starting point, not the contract — they may lag the validator. The authoritative contract is `schema`, and the only authoritative check that a graph is valid is publishing it (or the agent-validation endpoint). Do not parse `examples` as the schema.' documentation: anyOf: - additionalProperties: true type: object - type: 'null' title: Documentation description: Opaque, human-oriented authoring guidance for the node type — purpose, constraints, enum values, and variable-flow notes that the machine `schema` does not always express (e.g. a conditional's else-branch rule, or an iteration's sub-graph shape). Treat as an arbitrary object; use `docs_version` as its cache key. docs_version: anyOf: - type: string - type: 'null' title: Docs Version description: Opaque version string for `documentation`/`examples`, independent of `schema_version`. Bumps when the authoring guidance changes even if the underlying machine `schema` did not. When it trails the live `schema_version`, treat `documentation`/`examples` as guidance that may be stale and validate against the live `schema`. additionalProperties: false type: object required: - node_type - schema - schema_version title: NodeSchemaResponse description: JSON schema for a single node type. AgentRunStatus: type: string enum: - queued - running - succeeded - failed - cancelled - skipped - unknown title: AgentRunStatus description: Current execution status for an agent run. CreateAgentRequest: properties: organization_id: type: string format: uuid title: Organization Id description: ID of the organization that will own the agent. Required — Profound API keys are user-scoped, so the owning organization must be chosen explicitly. The caller must be a member of this organization. name: type: string minLength: 1 title: Name description: Display name for the agent. Must be non-empty. description: anyOf: - type: string - type: 'null' title: Description description: Short description of the agent. graph: anyOf: - additionalProperties: true type: object - type: 'null' title: Graph description: Initial workflow graph for the agent's draft version. Optional — an agent can be created empty and have its graph filled in later. additionalProperties: false type: object required: - organization_id - name title: CreateAgentRequest description: Request body for creating a draft agent. Agent: properties: id: type: string format: uuid title: Id description: Unique ID for the agent. organization_id: type: string format: uuid title: Organization Id description: Unique ID of the organization that owns the agent. name: type: string title: Name description: Display name of the agent. status: $ref: '#/components/schemas/AgentStatus' description: Current status of the agent. created_at: type: string format: date-time title: Created At description: When the agent was created. description: anyOf: - type: string - type: 'null' title: Description description: Short description of the agent, if provided. additionalProperties: false type: object required: - id - organization_id - name - status - created_at title: Agent description: Summary information for an agent. securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key BearerAuth: type: http scheme: bearer