CUcursor

Launch an agent

Start a new cloud agent to work on your repository

post/v0/agents

Request

  • Base URL
    https://api.cursor.com
  • Auth
    HTTP bearer

Request body

modelstring

Set to an explicit model ID for launch requests, or use "default" to use the configured default model. When omitted, Cursor resolves your user default model, then your team default model, then a system default.

Example request

{
  "prompt": {
    "text": "Add a README.md file with installation instructions",
    "images": [
      {
        "data": "iVBORw0KGgoAAAANSUhEUgAA...",
        "dimension": {
          "width": 1024,
          "height": 768
        }
      }
    ]
  },
  "model": "claude-4-sonnet",
  "source": {
    "repository": "https://github.com/your-org/your-repo",
    "ref": "main",
    "prUrl": "https://github.com/your-org/your-repo/pull/123"
  },
  "target": {
    "branchName": "feature/add-readme"
  },
  "webhook": {
    "url": "https://example.com/webhooks/cursor-agent",
    "secret": "your-webhook-secret-key-minimum-32-characters"
  }
}

Response

Agent created successfully

idstring required

Unique identifier for the cloud agent

namestring required

Name for the agent

status'CREATING' required

Initial status of the newly created agent

createdAtstring date-time required

When the agent was created

Example response

{
  "id": "bc_abc123",
  "name": "Add README Documentation",
  "status": "CREATING",
  "source": {
    "repository": "https://github.com/your-org/your-repo",
    "ref": "main"
  },
  "target": {
    "branchName": "cursor/add-readme-1234",
    "url": "https://cursor.com/agents?id=bc_abc123",
    "prUrl": "https://github.com/your-org/your-repo/pull/123"
  },
  "createdAt": "2024-01-15T10:30:00Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.