Anysphere Agents API

openapi: 3.0.3
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:
  responses:
    Forbidden:
      description: Authenticated but insufficient permissions, plan required, or feature unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Gone:
      description: Stream retention window has elapsed (`stream_expired`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Rate limit exceeded. Response includes `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Agent or run not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: Resource state conflict (`agent_busy`, `agent_archived`, `agent_id_conflict`, or `run_not_cancellable`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Invalid or missing API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Validation error or malformed request body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Artifact:
      type: object
      required:
      - path
      - sizeBytes
      - updatedAt
      properties:
        path:
          type: string
          minLength: 1
          description: Artifact path relative to the workspace's `artifacts/` directory.
          example: artifacts/screenshot.png
        sizeBytes:
          type: integer
          minimum: 0
          description: File size in bytes.
          example: 12345
        updatedAt:
          type: string
          format: date-time
          description: Last modified timestamp.
    RunGitBranch:
      type: object
      required:
      - repoUrl
      properties:
        repoUrl:
          type: string
          minLength: 1
          description: Repository URL the agent pushed to. Returned without the scheme (for example, `github.com/your-org/your-repo`).
          example: github.com/your-org/your-repo
        branch:
          type: string
          minLength: 1
          description: Branch name the agent pushed.
          example: cursor/add-readme-a1b2
        prUrl:
          type: string
          format: uri
          description: Pull request URL, when Cursor opened a PR.
          example: https://github.com/your-org/your-repo/pull/123
    ListRunsResponse:
      type: object
      required:
      - items
      properties:
        items:
          type: array
          description: Runs for this agent, newest first.
          items:
            $ref: '#/components/schemas/Run'
        nextCursor:
          type: string
          minLength: 1
          description: Cursor for fetching the next page of results. Omitted (not `null`) when there are no more pages.
    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'
    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.
    McpServer:
      oneOf:
      - $ref: '#/components/schemas/StdioMcpServer'
      - $ref: '#/components/schemas/RemoteMcpServer'
    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
    Run:
      type: object
      required:
      - id
      - agentId
      - status
      - createdAt
      - updatedAt
      properties:
        id:
          type: string
          description: Unique run identifier.
          example: run-00000000-0000-0000-0000-000000000001
        agentId:
          type: string
          description: ID of the agent this run belongs to.
          example: bc-00000000-0000-0000-0000-000000000001
        status:
          type: string
          enum:
          - CREATING
          - RUNNING
          - FINISHED
          - ERROR
          - CANCELLED
          - EXPIRED
          description: Current run status.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        durationMs:
          type: integer
          minimum: 0
          description: Wall-clock duration of the run in milliseconds. Populated once the run reaches a terminal status (`FINISHED`, `ERROR`, `CANCELLED`, `EXPIRED`).
          example: 12357
        result:
          type: string
          minLength: 1
          description: Final assistant reply text. Populated once the run terminates.
          example: Added README.md with installation instructions.
        git:
          allOf:
          - $ref: '#/components/schemas/RunGit'
          description: The agent's pushed branches and PRs. Populated once the agent has pushed at least one branch. Per-agent state, not per-run.
    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`,

                `integration_not_connected`, `validation_error`,

                `missing_body`, `invalid_model`, `invalid_branch_name`,

                `repository_required`, `repository_access`,

                `pr_resolution_failed`, `artifact_not_found`,

                `service_account_required`, `agent_not_found`,

                `run_not_found`, `agent_busy`, `agent_archived`,

                `agent_id_conflict`, `run_not_cancellable`,

                `rate_limit_exceeded`, `usage_limit_exceeded`,

                `stream_expired`, `stream_unavailable`,

                `invalid_last_event_id`, `client_cancelled`,

                `not_implemented`, `upstream_error`, and

                `internal_error`.

                '
            message:
              type: string
              description: Human-readable error message.
            helpUrl:
              type: string
              format: uri
              description: Optional follow-up link. Populated for codes like `integration_not_connected`.
            provider:
              type: string
              minLength: 1
              description: Optional provider identifier. Populated for codes like `integration_not_connected`.
    AgentMode:
      type: string
      enum:
      - agent
      - plan
      description: 'Conversation mode. `plan` explores and drafts a plan before coding; `agent` implements changes directly. On follow-up runs, omit to keep the conversation''s current mode; set explicitly to switch modes for that run.

        '
    RunGit:
      type: object
      description: 'The agent''s current pushed branches and pull requests. This is

        per-agent state — every run on the same agent returns the same

        `git` snapshot rather than only that run''s contributions. Use

        the agent''s `latestRunId` or the SSE stream to attribute work

        to a specific run.

        '
      required:
      - branches
      properties:
        branches:
          type: array
          description: Branches the agent has pushed. Stacked agents return one entry per branch.
          items:
            $ref: '#/components/schemas/RunGitBranch'
    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'
    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
    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
    ListAgentsResponse:
      type: object
      required:
      - items
      properties:
        items:
          type: array
          description: Agents, newest first.
          items:
            $ref: '#/components/schemas/AgentSummary'
        nextCursor:
          type: string
          minLength: 1
          description: Cursor for fetching the next page of results. Omitted (not `null`) when there are no more pages.
          example: bc-00000000-0000-0000-0000-000000000002
    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
    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.
    ModelRef:
      type: object
      required:
      - id
      properties:
        id:
          type: string
          minLength: 1
          description: Explicit model ID returned by GET /v1/models. Omit `model` from the request to use the configured default.
          example: composer-2
        params:
          type: array
          description: Per-model parameters such as reasoning effort or max mode. Use only parameters supported by the selected model.
          items:
            type: object
            required:
            - id
            - value
            properties:
              id:
                type: string
                minLength: 1
                example: thinking
              value:
                type: string
                minLength: 1
                example: high
    McpAuth:
      type: object
      additionalProperties: false
      required:
      - CLIENT_ID
      properties:
        CLIENT_ID:
          type: string
          mi

# --- 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