Programmatically create and manage Cursor Cloud Agents that work autonomously on your repositories. Separates a durable agent from one or more runs; supports SSE run streaming, artifacts, usage, models, repositories, and worker sub-tokens.
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: []
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: |
API key from Cursor Dashboard, supplied as the Basic
Authentication username with an empty password.
bearerAuth:
type: http
scheme: bearer
description: |
API key from Cursor Dashboard, supplied via
`Authorization: Bearer <key>`. Equivalent to Basic Auth.
schemas:
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]
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'
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'
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'
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']
StdioMcpServer:
type: object
additionalProperties: false
required:
- name
- command
properties:
name:
type: string
minLength: 1
description: MCP server name exposed to the agent.
example: 'github'
type:
type: string
enum: ['stdio']
description: Stdio MCP server. Defaults to `stdio` when `command` is provided.
example: 'stdio'
command:
type: string
minLength: 1
description: Command to start inside the cloud agent VM.
example: 'npx'
args:
type: array
description: Command arguments.
items:
type: string
example: ['-y', '@modelcontextprotocol/server-github']
env:
type: object
description: Environment variables passed to the stdio MCP server inside the VM.
additionalProperties:
type: string
example:
GITHUB_TOKEN: 'ghp_...'
RemoteMcpServer:
type: object
additionalProperties: false
required:
- name
- url
properties:
name:
type: string
minLength: 1
description: MCP server name exposed to the agent.
example: 'linear'
type:
type: string
enum: ['http', 'sse']
description: Remote MCP transport. Defaults to `http` when `url` is provided.
example: 'http'
url:
type: string
format: uri
description: HTTP or HTTPS URL for the remote MCP server. Userinfo in the URL is not allowed.
example: 'https://mcp.linear.app/sse'
headers:
type: object
description: Headers Cursor sends with every request to the remote MCP server.
additionalProperties:
type: string
example:
Authorization: 'Bearer lin_api_...'
auth:
$ref: '#/components/schemas/McpAuth'
McpServer:
oneOf:
- $ref: '#/components/schemas/StdioMcpServer'
- $ref: '#/components/schemas/RemoteMcpServer'
AgentSummary:
type: object
required:
- id
- status
- env
- url
- createdAt
- updatedAt
properties:
id:
type: string
description: Unique agent identifier.
example: 'bc-00000000-0000-0000-0000-000000000001'
name:
type: string
description: Display name. Auto-derived from the prompt when not supplied at create time. Omitted when no name has been set.
example: 'Add README with setup instructions'
status:
type: string
enum: ['ACTIVE', 'ARCHIVED']
description: Agent lifecycle state. Execution status lives on runs.
env:
$ref: '#/components/schemas/AgentEnv'
url:
type: string
format: uri
description: URL to view the agent in Cursor Web.
example: 'https://cursor.com/agents/bc-00000000-0000-0000-0000-000000000001'
createdAt:
type: string
format: date-time
description: When the agent was created.
updatedAt:
type: string
format: date-time
description: When the agent was last updated.
latestRunId:
type: string
description: ID of the most recent run on this agent, if any.
example: 'run-00000000-0000-0000-0000-000000000001'
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'
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'
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'
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.
RunStreamToolCallTruncation:
type: object
additionalProperties: false
properties:
args:
type: boolean
description: Present and true when the tool arguments were too large to include in the stream.
example: true
result:
type: boolean
description: Present and true when the tool result was too large to include in the stream.
example: true
JsonValue:
description: Any JSON value.
nullable: true
oneOf:
- type: string
- type: number
- type: boolean
- type: object
additionalProperties: true
- type: array
items: {}
RunStreamToolCallData:
type: object
additionalProperties: false
required:
- callId
- name
- status
properties:
callId:
type: string
minLength: 1
description: Stable identifier for one tool invocation across updates.
example: 'call-1'
name:
type: string
minLength: 1
description: Public tool name, such as `read_file`, `run_terminal_cmd`, or `mcp`.
example: 'read_file'
status:
type: string
enum: ['running', 'completed']
description: Tool invocation lifecycle status.
example: 'completed'
args:
allOf:
- $ref: '#/components/schemas/JsonValue'
description: Tool-specific JSON arguments, when available.
example:
path: 'README.md'
result:
allOf:
- $ref: '#/components/schemas/JsonValue'
description: Tool-specific JSON result, when available.
example:
success:
content: '# Project'
totalLines: 1
fileSize: 9
path: 'README.md'
truncated:
$ref: '#/components/schemas/RunStreamToolCallTruncation'
RunStreamToolCallEvent:
type: object
additionalProperties: false
required:
- event
- data
properties:
event:
type: string
enum: ['tool_call']
id:
type: string
description: Opaque SSE event id passed back via `Last-Event-ID` to resume the stream. Do not parse — the format is implementation-defined.
example: '1713033006000-0'
data:
$ref: '#/components/schemas/RunStreamToolCallData'
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'
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.
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'
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.
CreateAgentResponse:
type: object
required:
- agent
- run
properties:
agent:
$ref: '#/components/schemas/Agent'
run:
$ref: '#/components/schemas/Run'
CreateRunResponse:
type: object
required:
- run
properties:
run:
$ref: '#/components/schemas/Run'
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'
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.
IdResponse:
type: object
required:
- id
properties:
id:
type: string
description: Identifier of the affected resource.
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.
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'
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.
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
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.
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'
ApiKeyInfo:
type: object
required:
- apiKeyName
- createdAt
properties:
apiKeyName:
type: string
description: Display name of the API key.
example: 'Production API Key'
createdAt:
type: string
format: date-time
description: When the API key was created.
userId:
type: integer
minimum: 0
description: Numeric Cursor user ID of the API key's owner. Omitted for service-account / team API keys, which aren't tied to a specific user.
example: 42
userEmail:
type: string
format: email
description: Email of the API key's owner. Omitted for service-account / team API keys.
example: 'developer@example.com'
userFirstName:
type: string
minLength: 1
description: First name of the API key's owner, when populated.
example: 'Alex'
userLastName:
type: string
minLength: 1
description: Last name of the API key's owner, when populated.
example: 'Rivera'
ModelParameterValueDefinition:
type: object
required:
- value
properties:
value:
type: string
minLength: 1
description: Permitted value for the parameter.
example: 'true'
displayName:
type: string
minLength: 1
description: Human-readable label for the value.
example: 'Fast'
ModelParameterDefinition:
type: object
required:
- id
- values
properties:
id:
type: string
minLength: 1
description: Parameter identifier. Pass as `model.params[].id`.
example: 'fast'
displayName:
type: string
minLength: 1
description: Human-readable label for the parameter.
example: 'Fast'
values:
type: array
minItems: 1
description: Permitted values for this parameter.
items:
$ref: '#/components/schemas/ModelParameterValueDefinition'
ModelVariant:
type: object
required:
- params
- displayName
properties:
params:
type: array
description: Concrete parameter values that, combined with the parent model `id`, form a valid model selection. May be empty.
items:
type: object
required:
- id
- value
properties:
id:
type: string
minLength: 1
value:
type: string
minLength: 1
displayName:
type: string
minLength: 1
description: Human-readable label for this variant.
description:
type: string
minLength: 1
isDefault:
type: boolean
description: True for the variant Cursor selects when the user picks this model without explicit `params`.
ModelListItem:
type: object
required:
- id
- displayName
properties:
id:
type: string
minLength: 1
description: Pass this value as `model.id` when creating an agent.
example: 'composer-2'
displayName:
type: string
minLength: 1
description: Human-readable model name.
example: 'Composer 2'
description:
type: string
minLength: 1
aliases:
type: array
description: Alternate IDs that resolve to the same model.
items:
type: string
minLength: 1
example: ['composer-latest', 'composer']
parameters:
type: array
description: Per-model parameter definitions, when the model accepts parameters. Use these to populate `model.params`.
items:
$ref: '#/components/schemas/ModelParameterDefinition'
variants:
type: array
description: Concrete `id`+`params` combinations the model accepts.
items:
$ref: '#/components/schemas/ModelVariant'
ListModelsResponse:
type: object
required:
- items
properties:
items:
type: array
description: Recommended models. Use `id` (and optionally `params`) when creating an agent.
items:
$ref: '#/components/schemas/ModelListItem'
Repository:
type: object
required:
- url
properties:
url:
type: string
format: uri
description: GitHub repository URL.
example: 'https://github.com/your-org/your-repo'
ListRepositoriesResponse:
type: object
required:
- items
properties:
items:
type: array
items:
$ref: '#/components/schemas/Repository'
CreateSubTokenRequest:
type: object
description: Provide exactly one active team member identifier.
properties:
forUserEmail:
type: string
format: email
minLength: 1
description: Active team member email. Case-insensitive. Mutually exclusive with `forUserId`.
example: 'alice@company.com'
forUserId:
type: integ
# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/anysphere/refs/heads/main/openapi/anysphere-cloud-agents-openapi-original.yml