pages/cloud-agent/api/endpoints.txt

route: /docs/cloud-agent/api/endpoints
title: Cloud Agents API
description: Create and manage Cursor Cloud Agents programmatically with the run-based REST API.

Cloud Agents API
Public beta
The Cloud Agents API v1 is in public beta. APIs may change before general
availability.
The Cloud Agents API lets you programmatically launch and manage cloud agents that work on your repositories.
The Cloud Agents API accepts both Basic and Bearer authentication. Generate a user API key from Cursor Dashboard → API Keys, or use a service account API key.
For details on authentication methods, rate limits, and best practices, see the API Overview.
View the full OpenAPI specification for detailed schemas and examples.
Webhooks are coming soon. The legacy v0 API still supports them — see Webhooks.
Migrating from v0?
This API splits work into a durable agent plus per-prompt runs, replacing the flatter v0 surface. The legacy v0 reference remains available.
Endpoints
Create An Agent
POST/v1/agents
Create a Cloud Agent and immediately enqueue its initial run. The response returns both the durable agent and the initial run.
Request Body
prompt object (required)
The task prompt for the agent, including optional images.
prompt.text string (required)
The instruction text for the agent.
prompt.images array (optional)
Image inputs for the prompt. Each entry must include either data (base64-encoded bytes with a required mimeType) or url (an http or https URL that Cursor fetches). Maximum 5 images, 15 MB each. Supported MIME types: image/png, image/jpeg, image/gif, image/webp.
model object (optional)
Model selection. Omit this field to use the configured default. When omitted, Cursor resolves your user default model, then your team default model, then a system default.
model.id string (required if model provided)
An explicit model ID returned by GET /v1/models (for example, claude-4-sonnet-thinking).
model.params array (optional)
Per-model parameters to apply to the run, such as reasoning effort or max mode. Each item has an id and value. Use only parameters supported by the selected model — call GET /v1/models to discover the valid id/params combinations.
name string (optional)
Display name for the agent. Maximum 100 characters. When omitted, Cursor auto-derives a name from the prompt.
env object (optional)
Execution environment target. Use a named cloud environment, or route to a self-hosted pool or machine. Mutually exclusive with explicit repos when selecting a named Cursor-hosted environment.
env.type string (required if env provided)
Execution environment type. cloud uses Cursor-hosted VMs; pool and machine route to self-hosted workers.
env.name string (optional)
Named Cursor-hosted environment, self-hosted pool, or self-hosted machine name.
repos array (optional)
Repository configuration. Mutually exclusive with a named cloud environment. Omit both repos and env to start a no-repo agent. Maximum 20 repositories.
repos[0].url string (required)
GitHub repository URL (for example, https://github.com/your-org/your-repo). Required on every repo entry, including when prUrl is provided.
repos[0].startingRef string (optional)
Branch name or commit SHA to use as the starting point. Ignored when prUrl is provided.
repos[0].prUrl string (optional)
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 repos entry.
workOnCurrentBranch boolean (optional, default: false)
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. The branch the agent pushed shows up in the agent's git.branches[].
autoCreatePR boolean (optional)
Whether Cursor should open a pull request when the run completes.
skipReviewerRequest boolean (optional)
Whether to skip requesting the user as a reviewer when Cursor opens a PR. Only applies when autoCreatePR is true.
envVars object (optional)
Session-scoped environment variables for the cloud agent. Values are encrypted at rest, injected into the agent's shell, and deleted with the agent. Maximum 50 entries; names up to 255 bytes (can't start with CURSOR_), values up to 4096 bytes. 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 by inspecting the agent shell on a first run before relying on them in production.
mcpServers array (optional)
Inline MCP server definitions available to the agent. Maximum 50 servers. Remote servers support headers or OAuth auth; stdio servers run inside the cloud VM and can receive env. Server names must be unique.
mcpServers[0].name string (required)
The MCP server name exposed to the agent.
mcpServers[0].type string (optional)
Transport type: http, sse, or stdio. Defaults to http for remote servers with url, and stdio for servers with command.
mcpServers[0].url string (required for remote MCP)
HTTP or HTTPS URL for a remote MCP server. URLs with username or password are not allowed.
mcpServers[0].command string (required for stdio MCP)
Command to start a stdio MCP server inside the cloud agent VM. Use args and env for arguments and runtime secrets.
customSubagents array (optional)
Define custom subagents the main agent can delegate to during the run. Maximum 20 subagents. Each entry requires name, description, and prompt, plus an optional model (model ID string, ModelSelection object, or "inherit"). Names must be unique and cannot collide with built-ins (explore, debug, shell, computerUse, etc.).
mode string (optional, default: agent)
Initial conversation mode for the agent's first run. plan explores and drafts a plan before coding (Plan mode); agent implements changes directly.
agentId string (optional)
Client-supplied agent identifier in the form bc-<uuid>. Useful for idempotent create flows — re-POSTing the same agentId returns 409 agent_id_conflict rather than creating a duplicate. Cannot be combined with envVars; omit agentId so the server mints one when you need session secrets.
curl --request POST \
--url https://api.cursor.com/v1/agents \
-u YOUR_API_KEY: \
--header 'Content-Type: application/json' \
--data '{
"prompt": {
"text": "Add a README with setup instructions"
},
"model": {
"id": "composer-2",
"params": [
{ "id": "fast", "value": "true" }
]
},
"repos": [
{
"url": "https://github.com/your-org/your-repo",
"startingRef": "main"
}
],
"mcpServers": [
{
"name": "linear",
"type": "http",
"url": "https://mcp.linear.app/sse",
"headers": {
"Authorization": "Bearer YOUR_LINEAR_API_KEY"
}
},
{
"name": "github",
"type": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "YOUR_GITHUB_TOKEN"
}
],
"autoCreatePR": true
}'
Response:
{
"agent": {
"id": "bc-00000000-0000-0000-0000-000000000001",
"name": "Add README with setup instructions",
"status": "ACTIVE",
"env": {
"type": "cloud"
},
"repos": [
{
"url": "https://github.com/your-org/your-repo",
"startingRef": "main"
}
],
"workOnCurrentBranch": false,
"autoCreatePR": true,
"url": "https://cursor.com/agents/bc-00000000-0000-0000-0000-000000000001",
"createdAt": "2026-04-13T18:30:00.000Z",
"updatedAt": "2026-04-13T18:30:00.000Z",
"latestRunId": "run-00000000-0000-0000-0000-000000000001"
},
"run": {
"id": "run-00000000-0000-0000-0000-000000000001",
"agentId": "bc-00000000-0000-0000-0000-000000000001",
"status": "CREATING",
"createdAt": "2026-04-13T18:30:00.000Z",
"updatedAt": "2026-04-13T18:30:00.000Z"
}
List Agents
GET/v1/agents
List agents for the authenticated user, newest first.
Query Parameters
limit number (optional)
Number of agents to return. Default: 20, Max: 100.
cursor string (op
…