Profound Agents API

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: s

# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/profound/refs/heads/main/openapi/profound-agents-api-openapi.yml