Anysphere Agents API

openapi: 3.2.0
info:
  title: Cursor Cloud Agents API
  description: 'Programmatically create and manage Cursor Cloud Agents that work

    autonomously on your repositories. v1 separates a durable agent

    from one or more runs: each prompt submission creates a run on the

    agent. Streaming and cancellation are scoped to the active run.

    '
  version: 1.0.0
  contact:
    email: background-agent-feedback@cursor.com
servers:
- url: https://api.cursor.com
  description: Production server
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Agents
paths:
  /v1/agents:
    post:
      summary: Create an agent
      description: 'Create a Cloud Agent and immediately enqueue its initial run.

        The response contains both the durable `agent` and the initial

        `run`.

        '
      operationId: createAgent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRequest'
      responses:
        '201':
          description: Agent created and initial run enqueued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAgentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      tags:
      - Agents
    get:
      summary: List agents
      description: List agents for the authenticated user, newest first.
      operationId: listAgents
      parameters:
      - name: limit
        in: query
        required: false
        description: Number of agents to return.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: cursor
        in: query
        required: false
        description: Pagination cursor from the previous response.
        schema:
          type: string
          minLength: 1
      - name: prUrl
        in: query
        required: false
        description: Filter agents by GitHub pull request URL.
        schema:
          type: string
          format: uri
      - name: includeArchived
        in: query
        required: false
        description: Whether to include archived agents.
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: Agents retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAgentsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      tags:
      - Agents
  /v1/agents/{id}:
    get:
      summary: Get an agent
      description: Retrieve durable metadata for an agent. Execution status lives on runs.
      operationId: getAgent
      parameters:
      - $ref: '#/components/parameters/AgentId'
      responses:
        '200':
          description: Agent retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      tags:
      - Agents
    delete:
      summary: Delete an agent permanently
      description: Permanently delete an agent. This action is irreversible. Use POST /v1/agents/{id}/archive for reversible removal.
      operationId: deleteAgent
      parameters:
      - $ref: '#/components/parameters/AgentId'
      responses:
        '200':
          description: Agent deleted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      tags:
      - Agents
  /v1/agents/{id}/runs:
    post:
      summary: Create a run
      description: 'Send a follow-up prompt to an existing active agent. The new

        run uses the agent''s current conversation and workspace state.

        Only one run can be active per agent at a time.

        '
      operationId: createRun
      parameters:
      - $ref: '#/components/parameters/AgentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRunRequest'
      responses:
        '201':
          description: Run created and enqueued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateRunResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      tags:
      - Agents
    get:
      summary: List runs
      description: List runs for an agent, newest first.
      operationId: listRuns
      parameters:
      - $ref: '#/components/parameters/AgentId'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: cursor
        in: query
        required: false
        description: Pagination cursor from the previous response.
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: Runs retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListRunsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      tags:
      - Agents
  /v1/agents/{id}/runs/{runId}:
    get:
      summary: Get a run
      description: Retrieve status and timestamps for a specific run.
      operationId: getRun
      parameters:
      - $ref: '#/components/parameters/AgentId'
      - $ref: '#/components/parameters/RunId'
      responses:
        '200':
          description: Run retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Run'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      tags:
      - Agents
  /v1/agents/{id}/runs/{runId}/stream:
    get:
      summary: Stream a run
      description: "Stream Server-Sent Events for one run. Event types are\n`status`, `assistant`, `thinking`, `tool_call`,\n`interaction_update`, `heartbeat`, `result`, `error`, and\n`done`.\n\n- `status` carries `{ runId, status }`. It has no `id` line\n  and is replayed at the top of every reconnect.\n- `result` carries `{ runId, status, text?, durationMs?,\n  git? }`; `text` is the final assistant reply, `durationMs`\n  the wall-clock duration, and `git` mirrors `Run.git`.\n- `interaction_update` carries the richer SDK-shape update\n  used by the TypeScript SDK and is emitted alongside the\n  simplified events that share the same event id. Use this if\n  you want the full SDK stream; otherwise handle the simplified\n  events and ignore it.\n\nReconnect with the `Last-Event-ID` header to resume after a\ndisconnect; the event ID must belong to the requested run\notherwise the endpoint returns `400 invalid_last_event_id`.\nResponses include the `X-Cursor-Stream-Retention-Seconds`\nheader; after the retention window the endpoint may return\n`410 stream_expired`. `tool_call` event data uses the\n`RunStreamToolCallData` schema.\n"
      operationId: streamRun
      parameters:
      - $ref: '#/components/parameters/AgentId'
      - $ref: '#/components/parameters/RunId'
      - name: Last-Event-ID
        in: header
        required: false
        description: Resume from a previously received event ID for this run.
        schema:
          type: string
      responses:
        '200':
          description: SSE stream of run events.
          headers:
            X-Cursor-Stream-Retention-Seconds:
              description: Server-side stream retention window in seconds.
              schema:
                type: integer
          content:
            text/event-stream:
              schema:
                type: string
              examples:
                toolCall:
                  summary: Tool call events
                  value: 'id: 1713033005000-0

                    event: tool_call

                    data: {"callId":"call-1","name":"read_file","status":"running","args":{"path":"README.md"}}


                    id: 1713033006000-0

                    event: tool_call

                    data: {"callId":"call-1","name":"read_file","status":"completed","args":{"path":"README.md"},"result":{"success":{"content":"# Project","totalLines":1,"fileSize":9,"path":"README.md"}}}

                    '
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '410':
          $ref: '#/components/responses/Gone'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      tags:
      - Agents
  /v1/agents/{id}/runs/{runId}/cancel:
    post:
      summary: Cancel a run
      description: 'Cancel the active run for an agent. Cancellation is terminal —

        the run transitions to `CANCELLED`. Cancelling a run that is

        already terminal or was never active returns

        `409 run_not_cancellable`. To continue the conversation,

        create a new run on the same agent.

        '
      operationId: cancelRun
      parameters:
      - $ref: '#/components/parameters/AgentId'
      - $ref: '#/components/parameters/RunId'
      responses:
        '200':
          description: Run cancelled successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      tags:
      - Agents
  /v1/agents/{id}/usage:
    get:
      summary: Get agent usage
      description: 'Retrieve token usage for an agent, broken down per run.

        `totalUsage` sums input, output, and cache token counts across

        every run on the agent, and `runs` lists the same breakdown for

        each run. Token usage mirrors the `tokenUsage` shape on the team

        usage events endpoint.


        This endpoint is in early access. When it isn''t enabled for the

        account it returns `403 feature_unavailable`. An unknown `runId`

        returns `404 run_not_found`.

        '
      operationId: getAgentUsage
      parameters:
      - $ref: '#/components/parameters/AgentId'
      - name: runId
        in: query
        required: false
        description: Scope usage to a single run. Omit to return usage for every run on the agent.
        schema:
          type: string
          example: run-00000000-0000-0000-0000-000000000001
      responses:
        '200':
          description: Usage retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentUsageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      tags:
      - Agents
  /v1/agents/{id}/archive:
    post:
      summary: Archive an agent
      description: Archive an agent. Archived agents remain readable but cannot accept new runs until unarchived.
      operationId: archiveAgent
      parameters:
      - $ref: '#/components/parameters/AgentId'
      responses:
        '200':
          description: Agent archived successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      tags:
      - Agents
  /v1/agents/{id}/unarchive:
    post:
      summary: Unarchive an agent
      description: Unarchive an agent so it can accept new runs again.
      operationId: unarchiveAgent
      parameters:
      - $ref: '#/components/parameters/AgentId'
      responses:
        '200':
          description: Agent unarchived successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      tags:
      - Agents
  /v1/agents/{id}/artifacts:
    get:
      summary: List artifacts
      description: 'List artifacts produced by an agent. Each artifact''s `path` is

        relative to the workspace''s `artifacts/` directory. Pass that

        `path` to GET /v1/agents/{id}/artifacts/download to obtain a

        presigned download URL.

        '
      operationId: listArtifacts
      parameters:
      - $ref: '#/components/parameters/AgentId'
      responses:
        '200':
          description: Artifacts retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListArtifactsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      tags:
      - Agents
  /v1/agents/{id}/artifacts/download:
    get:
      summary: Download an artifact
      description: 'Retrieve a temporary 15-minute presigned S3 URL for an

        artifact. The `path` query parameter must be a relative path

        under `artifacts/` returned by GET /v1/agents/{id}/artifacts.

        '
      operationId: downloadArtifact
      parameters:
      - $ref: '#/components/parameters/AgentId'
      - name: path
        in: query
        required: true
        description: Relative artifact path under `artifacts/`.
        schema:
          type: string
          minLength: 1
          example: artifacts/screenshot.png
      responses:
        '200':
          description: Presigned URL retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadArtifactResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      tags:
      - Agents
components:
  schemas:
    Agent:
      allOf:
      - $ref: '#/components/schemas/AgentSummary'
      - type: object
        properties:
          repos:
            type: array
            description: Repository configuration. Empty for no-repo agents.
            items:
              $ref: '#/components/schemas/RepoConfig'
          workOnCurrentBranch:
            type: boolean
            description: When `false` (the default), Cursor pushes commits to a new auto-generated branch. When `true`, commits land on the existing head branch.
            example: false
          autoCreatePR:
            type: boolean
            description: Whether Cursor opens a pull request when the run completes.
            example: true
          skipReviewerRequest:
            type: boolean
            description: Whether to skip requesting the user as a reviewer when Cursor opens a PR.
          customSubagents:
            type: array
            description: Custom subagents defined at create time. Omitted when none were provided.
            items:
              $ref: '#/components/schemas/CustomSubagent'
    RunUsage:
      type: object
      required:
      - id
      - usage
      properties:
        id:
          type: string
          minLength: 1
          description: Run identifier.
          example: run-00000000-0000-0000-0000-000000000001
        usageUuid:
          type: string
          minLength: 1
          description: Internal usage identifier for the run. Omitted when the run has no recorded usage yet.
          example: 00000000-0000-0000-0000-000000000001
        usage:
          allOf:
          - $ref: '#/components/schemas/UsageTokenUsage'
          description: Token usage for this run. Runs without recorded usage report zeros across all fields.
    AgentEnv:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - cloud
          - pool
          - machine
          description: Execution environment type. `cloud` uses Cursor-hosted VMs; `pool` and `machine` route to self-hosted workers.
          example: cloud
        name:
          type: string
          minLength: 1
          description: Named Cursor-hosted environment, self-hosted pool, or self-hosted machine name.
          example: Release workspace
    CreateRunRequest:
      type: object
      required:
      - prompt
      properties:
        prompt:
          type: object
          required:
          - text
          properties:
            text:
              type: string
              minLength: 1
              description: Follow-up instruction text.
              example: Also add troubleshooting steps
            images:
              type: array
              maxItems: 5
              items:
                $ref: '#/components/schemas/Image'
              description: Image inputs for the follow-up. Each entry must provide either `data` (with required `mimeType`) or `url`. Maximum 5 images, 15 MB each.
        mcpServers:
          type: array
          maxItems: 50
          description: Inline MCP server definitions for this follow-up run. When provided, these definitions replace any create-time inline MCP servers for this run.
          items:
            $ref: '#/components/schemas/McpServer'
        mode:
          $ref: '#/components/schemas/AgentMode'
    ListArtifactsResponse:
      type: object
      required:
      - items
      properties:
        items:
          type: array
          description: Artifacts produced by the agent. Returns at most 100 artifacts.
          items:
            $ref: '#/components/schemas/Artifact'
    CreateAgentRequest:
      type: object
      required:
      - prompt
      properties:
        prompt:
          type: object
          required:
          - text
          properties:
            text:
              type: string
              minLength: 1
              description: Task instruction for the agent.
              example: Add a README with setup instructions
            images:
              type: array
              maxItems: 5
              items:
                $ref: '#/components/schemas/Image'
              description: Image inputs. Each entry must provide either `data` (with required `mimeType`) or `url`. Maximum 5 images, 15 MB each.
        model:
          $ref: '#/components/schemas/ModelRef'
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: Display name for the agent. Auto-derived from the prompt when omitted.
          example: Add README with setup instructions
        agentId:
          type: string
          minLength: 1
          pattern: ^bc-[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
          description: Optional client-supplied agent identifier in `bc-<uuid>` form. Re-POSTing the same `agentId` returns `409 agent_id_conflict` instead of creating a duplicate. Cannot be combined with `envVars`; omit `agentId` so the server mints one when you need session secrets.
          example: bc-00000000-0000-0000-0000-000000000001
        env:
          $ref: '#/components/schemas/AgentEnv'
        repos:
          type: array
          maxItems: 20
          description: 'Repository configuration. Mutually exclusive with a named cloud environment. Omit both `repos` and `env` (or pass `repos: []`) to start a no-repo agent.'
          items:
            $ref: '#/components/schemas/RepoConfig'
        workOnCurrentBranch:
          type: boolean
          description: 'When `false` (the default), Cursor pushes commits to a new

            auto-generated branch (`cursor/...`) based on

            `repos[0].startingRef` (or the PR base ref when `prUrl`

            is set). When `true`, Cursor pushes directly to that

            starting ref — for a non-PR create, that''s the branch you

            passed in `startingRef`; for a `prUrl` create, that''s the

            PR''s head branch.

            '
          default: false
        autoCreatePR:
          type: boolean
          description: Whether Cursor should open a pull request when the run completes.
          default: false
        skipReviewerRequest:
          type: boolean
          description: Whether to skip requesting the user as a reviewer when Cursor opens a PR. Only applies when `autoCreatePR` is true.
          default: false
        envVars:
          type: object
          maxProperties: 50
          description: 'Session-scoped environment variables for the cloud agent.

            Values are encrypted at rest, injected into the agent''s

            shell, and deleted with the agent. Names must be non-empty,

            255 bytes or less, and cannot start with `CURSOR_`. Values

            must be non-empty and 4096 bytes or less. Cannot be

            combined with a client-supplied `agentId`.


            Beta: `envVars` is rolling out. If it isn''t enabled for

            your account yet, the field is silently ignored on create

            rather than failing the request — verify the values are

            present on a first run before relying on them in

            production.

            '
          additionalProperties:
            type: string
            minLength: 1
            maxLength: 4096
        mcpServers:
          type: array
          maxItems: 50
          description: Inline MCP server definitions available to the initial run. Remote servers support `headers` or OAuth `auth`; stdio servers run inside the cloud agent VM and can receive `env`. Server names must be unique.
          items:
            $ref: '#/components/schemas/McpServer'
        customSubagents:
          type: array
          maxItems: 20
          description: Custom subagents the main agent can delegate to. Names must be unique and not collide with built-ins.
          items:
            $ref: '#/components/schemas/CustomSubagent'
        mode:
          allOf:
          - $ref: '#/components/schemas/AgentMode'
          default: agent
          description: Initial conversation mode for the agent's first run.
    AgentUsageResponse:
      type: object
      required:
      - totalUsage
      - runs
      properties:
        totalUsage:
          allOf:
          - $ref: '#/components/schemas/UsageTokenUsage'
          description: Token usage summed across the returned runs.
        runs:
          type: array
          description: Per-run usage, one entry per run (or a single entry when `runId` is set).
          items:
            $ref: '#/components/schemas/RunUsage'
    McpAuth:
      type: object
      additionalProperties: false
      required:
      - CLIENT_ID
      properties:
        CLIENT_ID:
          type: string
          minLength: 1
          description: OAuth client ID for the MCP server.
          example: client-id
        CLIENT_SECRET:
          type: string
          description: OAuth client secret for the MCP server.
          example: client-secret
        scopes:
          type: array
          description: OAuth scopes to request for the MCP server.
          items:
            type: string
            minLength: 1
          example:
          - file_content:read
    ImageDimension:
      type: object
      required:
      - width
      - height
      properties:
        width:
          type: integer
          minimum: 1
          description: Width in pixels
        height:
          type: integer
          minimum: 1
          description: Height in pixels
    Image:
      type: object
      description: 'An image input. Provide exactly one of `data` or `url`. When

        `data` is provided, `mimeType` is required. When `url` is

        provided, Cursor fetches the image and `mimeType` must be

        omitted.

        '
      properties:
        data:
          type: string
          minLength: 1
          description: Base64 encoded image bytes (max 15 MB). Mutually exclusive with `url`.
          example: iVBORw0KGgoAAAANSUhEUgAA...
        url:
          type: string
          format: uri
          description: HTTP or HTTPS URL Cursor fetches. Mutually exclusive with `data`.
          example: https://example.com/screenshot.png
        mimeType:
          type: string
          minLength: 1
          description: MIME type of the image bytes. Required when `data` is provided; must be omitted when `url` is provided. Supported types are `image/png`, `image/jpeg`, `image/gif`, and `image/webp`.
          example: image/png
        dimension:
          $ref: '#/components/schemas/ImageDimension'
      oneOf:
      - required:
        - data
        - mimeType
        not:
          required:
          - url
      - required:
        - url
        not:
          anyOf:
          - required:
            - data
          - required:
            - mimeType
    UsageTokenUsage:
      type: object
      required:
      - inputTokens
      - outputTokens
      - cacheWriteTokens
      - cacheReadTokens
      - totalTokens
      properties:
        inputTokens:
          type: integer
          minimum: 0
          description: Input tokens consumed.
          example: 6320
        outputTokens:
          type: integer
          minimum: 0
          description: Output tokens generated.
          example: 1450
        cacheWriteTokens:
          type: integer
          minimum: 0
          description: Tokens written to cache.
          example: 7100
        cacheReadTokens:
          type: integer
          minimum: 0
          description: Tokens read from cache.
          example: 21300
        totalTokens:
          type: integer
          minimum: 0
          description: Sum of the four token counts above.
          example: 36170
    DownloadArtifactResponse:
      type: object
      required:
      - url
      - expiresAt
      properties:
        url:
          type: string
          format: uri
          description: Temporary 15-minute presigned S3 URL for downloading the artifact.
          example: https://cloud-agent-artifacts.s3.us-east-1.amazonaws.com/...
        expiresAt:
          type: string
          format: date-time
          description: When the presigned URL expires.
    CreateRunResponse:
      type: object
      required:
      - run
      properties:
        run:
          $ref: '#/components/schemas/Run'
    RepoConfig:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          minLength: 1
          description: GitHub repository URL. Required on every repo entry, including when `prUrl` is provided.
          example: https://github.com/your-org/your-repo
        startingRef:
          type: string
          minLength: 1
          description: Branch name or commit SHA to use as the starting point. Ignored when `prUrl` is provided.
          example: main
        prUrl:
          type: string
          format: uri
          description: GitHub pull request URL. When provided, the agent works on this PR's repository and branches; `startingRef` is ignored. `url` must still be set on the same entry.
          example: https://github.com/your-org/your-repo/pull/123
    CustomSubagent:
      type: object
      additionalProperties: false
      required:
      - name
      - description
      - prompt
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: Subagent name. Must be unique within `customSubagents` and cannot collide with built-ins (for example, `explore`, `shell`, `debug`, `computerUse`, `cursorGuide`).
          example: frontend-reviewer
        description:
          type: string
          minLength: 1
          maxLength: 1000
          description: Short summary used by the main agent to decide when to delegate.
        prompt:
          type: string
          minLength: 1
          maxLength: 8192
          description: System prompt the subagent receives when invoked.
        model:
          oneOf:
          - type: string
            enum:
            - inherit
            description: Use the parent agent's model selection.
          - type: string
            minLength: 1
            description: An explicit model ID.
            example: claude-4.6-sonnet-thinking
          - $ref: '#/components/schemas/ModelRef'
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: 'Machine-readable error code. Possible values include

                `unauthorized`, `api_key_not_found`, `plan_required`,

                `role_forbidden`, `feature_unavailable`,



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