Cursor - Build Software Faster

Launch an agent

curl --request POST \
  --url https://api.cursor.com/v0/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": {
    "text": "Add a README.md file with installation instructions",
    "images": [
      {
        "data": "iVBORw0KGgoAAAANSUhEUgAA...",
        "dimension": {
          "width": 1024,
          "height": 768
        }
      }
    ]
  },
  "source": {
    "repository": "https://github.com/your-org/your-repo",
    "ref": "main"
  },
  "model": "claude-4-sonnet",
  "target": {
    "autoCreatePr": false,
    "branchName": "feature/add-readme"
  },
  "webhook": {
    "url": "https://example.com/webhooks/cursor-agent",
    "secret": "your-webhook-secret-key-minimum-32-characters"
  }
}
'

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

POST

agents

Launch an agent

curl --request POST \
  --url https://api.cursor.com/v0/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": {
    "text": "Add a README.md file with installation instructions",
    "images": [
      {
        "data": "iVBORw0KGgoAAAANSUhEUgAA...",
        "dimension": {
          "width": 1024,
          "height": 768
        }
      }
    ]
  },
  "source": {
    "repository": "https://github.com/your-org/your-repo",
    "ref": "main"
  },
  "model": "claude-4-sonnet",
  "target": {
    "autoCreatePr": false,
    "branchName": "feature/add-readme"
  },
  "webhook": {
    "url": "https://example.com/webhooks/cursor-agent",
    "secret": "your-webhook-secret-key-minimum-32-characters"
  }
}
'

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

Authorizations

Authorization

string

header

required

API key from Cursor Dashboard

Body

application/json

prompt

object

required

Mostrar atributos secundarios

prompt.text

string

required

The task or instructions for the agent to execute

Minimum string length: 1

Example:

"Add a README.md file with installation instructions"

prompt.images

object[]

Optional array of base64 encoded images (max 5)

Maximum array length: 5

Mostrar atributos secundarios

prompt.images.data

string

required

Base64 encoded image data

Minimum string length: 1

Example:

"iVBORw0KGgoAAAANSUhEUgAA..."

prompt.images.dimension

object

Mostrar atributos secundarios

prompt.images.dimension.width

integer

required

Width must be a positive integer

Rango requerido: x >= 1

prompt.images.dimension.height

integer

required

Height must be a positive integer

Rango requerido: x >= 1

Example:

[
  {
    "data": "iVBORw0KGgoAAAANSUhEUgAA...",
    "dimension": { "width": 1024, "height": 768 }
  }
]

source

object

required

Mostrar atributos secundarios

source.repository

string

required

The GitHub repository URL

Minimum string length: 1

Example:

"https://github.com/your-org/your-repo"

source.ref

string

Git ref (branch/tag) to use as the base branch

Minimum string length: 1

Example:

"main"

model

string

The LLM to use

Minimum string length: 1

Example:

"claude-4-sonnet"

target

object

Mostrar atributos secundarios

target.autoCreatePr

boolean

default:false

Whether to automatically create a pull request when the agent completes

target.branchName

string

Custom branch name for the agent to create

Minimum string length: 1

Example:

"feature/add-readme"

webhook

object

Mostrar atributos secundarios

webhook.url

string<uri>

required

URL to receive webhook notifications about agent status changes

Maximum string length: 2048

Example:

"https://example.com/webhooks/cursor-agent"

webhook.secret

string

Secret key for webhook payload verification

Required string length: 32 - 256

Example:

"your-webhook-secret-key-minimum-32-characters"

Response

Agent created successfully

string

required

Unique identifier for the background agent

Example:

"bc_abc123"

name

string

required

Name for the agent

Example:

"Add README Documentation"

status

enum<string>

required

Initial status of the newly created agent

Opciones disponibles:

CREATING

Example:

"CREATING"

source

object

required

Mostrar atributos secundarios

source.repository

string

required

The GitHub repository URL

Example:

"https://github.com/your-org/your-repo"

source.ref

string

Git ref (branch/tag) used as the base branch

Example:

"main"

target

object

required

Mostrar atributos secundarios

target.url

string

required

URL to view the agent in Cursor Web

Example:

"https://cursor.com/agents?id=bc_abc123"

target.branchName

string

The Git branch name where the agent is working

Example:

"cursor/add-readme-1234"

target.autoCreatePr

boolean

Whether a pull request will be automatically created

Example:

false

createdAt

string<date-time>

required

When the agent was created

Example:

"2024-01-15T10:30:00Z"

Conversación del agente Agregar seguimiento

⌘I

Primeros pasos

Núcleo

Contexto

Integraciones

Modelos

Configuración

Seguridad

Cuenta

Solución de problemas

Iniciar un agente

Authorizations

Body

Response