METAGROK
API / create-a-cloud-agent-via-api

API

Create a Cloud Agent with the Cloud Agents API

create-a-cloud-agent-via-api

Launch a durable Cloud Agent and enqueue its first run with POST https://api.cursor.com/v1/agents. Official reference: Cloud Agents API → Create An Agent.

The Cloud Agents API v1 is in public beta. Authenticate with Basic auth (API key as username, empty password) or Authorization: Bearer YOUR_API_KEY. Create a user key at Cursor Dashboard → API Keys, or use a service account key. Availability: Beta (all plans) per the API overview.

The create response returns both the durable agent and the initial run. Later prompts go to Create A Run on the same agent id.

Required body

Field Rules
prompt.text Required instruction string for the first run.
prompt.images Optional. Max 5 images, 15 MB each. Each entry needs data + mimeType (base64) or url (http/https). MIME: image/png, image/jpeg, image/gif, image/webp.

Common optional fields

Field Rules
model.id Explicit model from GET /v1/models. Omit model to use user → team → system default.
model.params Array of { id, value } pairs supported by that model.
name Display name, max 100 chars. Omit to auto-name from the prompt.
env { type: "cloud" | "pool" | "machine", name? }. Named cloud env is mutually exclusive with explicit repos.
repos Up to 20 repos. Each needs url. Optional startingRef or prUrl (with url still set; startingRef ignored when prUrl is set). Omit repos and env for a no-repo agent.
workOnCurrentBranch Default false → push to a new cursor/... branch. true → push to the starting ref / PR head.
autoCreatePR Open a pull request when the run finishes.
skipReviewerRequest Only with autoCreatePR: true. Skip requesting you as reviewer.
envVars Up to 50 session secrets (name ≤255 bytes, value ≤4096 bytes; names cannot start with CURSOR_). Cannot combine with client-supplied agentId. Beta: may be silently ignored until enabled — verify on a first run.
mcpServers Up to 50 inline MCP servers (http/sse/stdio).
customSubagents Up to 20 custom subagents (name, description, prompt; optional model). Names cannot collide with built-ins.
mode agent (default) or plan.
agentId Client-supplied bc-… for idempotent create. Re-POST returns 409 agent_id_conflict. Cannot combine with envVars.

Request

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"
      }
    ],
    "autoCreatePR": true
  }'

Worker pool (any-repo when repos is omitted):

curl --request POST \
  --url https://api.cursor.com/v1/agents \
  -u YOUR_API_KEY: \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": {
      "text": "Clone the payments service and add a health check"
    },
    "env": {
      "type": "pool",
      "name": "sandbox"
    }
  }'

An unknown pool name returns 400 instead of waiting forever.

Response shape

{
  "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"
  }
}

Save agent.id and run.id (also mirrored on agent.latestRunId). Poll Get A Run, or stream the run, for progress. OpenAPI schemas live on the same docs page.

Related how-tos