API Cloud Agents

Beta público

A API Cloud Agents v1 está em beta público. As APIs podem mudar antes da disponibilidade geral.

A API Cloud Agents permite iniciar e gerenciar programaticamente agentes na nuvem que trabalham nos seus repositórios.

A API Cloud Agents aceita autenticação Basic e Bearer. Gere uma chave de API de usuário no dashboard do Cherri Code → Chaves de API ou use uma chave de API de conta de serviço.
Para mais detalhes sobre métodos de autenticação, limite de taxa e boas práticas, consulte a Visão geral da API.
Veja a especificação OpenAPI completa para ver esquemas detalhados e exemplos.
Webhooks estarão disponíveis em breve. A API v0 legada ainda oferece suporte a eles — consulte Webhooks.

Migrando da v0?

Esta API divide o trabalho em um agente persistente mais execuções por prompt, substituindo a interface mais simples da v0. A referência legada da v0 continua disponível.

O limite de 15 MB por imagem indicado abaixo se aplica às imagens enviadas pela API. Os anexos na Web em cursor.com/agents usam limites separados. Consulte Limites de anexos do Cloud Agent na Web.

Endpoints

Criar um agente

POST/v1/agents

Crie um Cloud Agent e enfileire imediatamente sua execução inicial. A resposta retorna tanto o agent durável quanto o run inicial.

Corpo da solicitação

prompt objeto (obrigatório)

O prompt da tarefa para o agente, incluindo imagens opcionais.

prompt.text string (obrigatório)

O texto de instrução para o agente.

prompt.images array (opcional)

Entradas de imagem para o prompt. Cada entrada deve incluir data (bytes codificados em base64 com um mimeType obrigatório) ou url (uma URL http ou https que o Cherri Code consulta). Máximo de 5 imagens, 15 MB cada. Tipos MIME suportados: image/png, image/jpeg, image/gif, image/webp.

model objeto (opcional)

Seleção de modelo. Omita este campo para usar o padrão configurado. Quando omitido, o Cherri Code resolve primeiro o modelo padrão do usuário, depois o modelo padrão da equipe e, por fim, um modelo padrão do sistema.

model.id string (obrigatório se model for fornecido)

Um ID de modelo explícito retornado por GET /v1/models (por exemplo, claude-4-sonnet-thinking).

model.params array (opcional)

Parâmetros por modelo a serem aplicados à execução, como nível de esforço de raciocínio ou tamanho da janela de contexto. Cada item possui um id e um value. Use apenas parâmetros suportados pelo modelo selecionado — chame GET /v1/models para descobrir as combinações válidas de id/params.

name string (opcional)

Nome exibido do agente. Máximo de 100 caracteres. Quando omitido, o Cherri Code deriva automaticamente um nome a partir do prompt.

env objeto (opcional)

Destino do ambiente de execução. Use um ambiente cloud nomeado, ou direcione para um pool ou machine hospedado por você. É mutuamente exclusivo com repos explícitos ao selecionar um ambiente hospedado pelo Cherri Code com nome.

env.type string (obrigatório se env for fornecido)

Tipo de ambiente de execução. cloud usa VMs hospedadas pelo Cursor; pool e machine direcionam para seus próprios workers.

env.name string (opcional)

Nome do ambiente hospedado pelo Cherri Code, do pool ou da máquina. Para env.type: "pool", este é o nome do pool (o valor padrão é default quando omitido). Um nome de pool desconhecido retorna 400 em vez de ficar na fila indefinidamente.

repos matriz (opcional)

Configuração do repositório. Mutuamente exclusiva em relação a um ambiente de nuvem nomeado. Omita tanto repos quanto env para iniciar um agente sem repositório. Você também pode omitir repos quando env.type for pool para direcionar a um pool any-repo. Máximo de 20 repositórios.

repos[0].url string (obrigatório)

URL do repositório no GitHub (por exemplo, https://github.com/your-org/your-repo). Obrigatório em toda entrada de repositório, inclusive quando prUrl for fornecido.

repos[0].startingRef string (opcional)

Nome do branch ou SHA do commit a ser usado como ponto de partida. Ignorado quando prUrl for fornecido.

repos[0].prUrl string (opcional)

URL do pull request do GitHub. Quando fornecida, o agente atua no repositório e nos branches deste PR; startingRef é ignorado. url ainda deve ser definido na mesma entrada de repos.

workOnCurrentBranch booleano (opcional, padrão: false)

Quando false (o padrão), o Cherri Code envia os commits para um novo branch gerado automaticamente (cursor/...) baseado em repos[0].startingRef (ou na ref base do PR quando prUrl estiver definido). Quando true, o Cherri Code envia diretamente para essa ref inicial — para uma criação sem PR, esse é o branch que você passou em startingRef; para uma criação com prUrl, esse é o branch head do PR. O branch para o qual o agente enviou aparece em git.branches[] do agente.

autoCreatePR booleano (opcional)

Se o Cherri Code deve abrir um pull request quando a execução for concluída.

skipReviewerRequest booleano (opcional)

Se deve pular a solicitação do usuário como revisor quando o Cherri Code abrir um PR. Aplica-se apenas quando autoCreatePR for true.

envVars objeto (opcional)

Variáveis de ambiente com escopo de sessão para o agente em nuvem. Os valores são criptografados quando armazenados, injetados no shell do agente e excluídos junto com ele. Máximo de 50 entradas; nomes de até 255 bytes (não podem começar com CURSOR_), valores de até 4096 bytes. Não pode ser combinado com um agentId fornecido pelo cliente.

Beta: envVars está sendo liberado gradualmente. Se ainda não estiver habilitado para sua conta, o campo é ignorado silenciosamente na criação em vez de fazer a solicitação falhar — verifique se os valores estão presentes inspecionando o shell do agente na primeira execução antes de confiar neles em produção.

mcpServers array (opcional)

Definições inline de servidores MCP disponíveis para o agente. Máximo de 50 servidores. Servidores remotos suportam headers ou auth do OAuth; servidores stdio são executados dentro da VM na nuvem e podem receber env. Os nomes dos servidores devem ser únicos.

mcpServers[0].name string (obrigatório)

O nome do servidor MCP exposto ao agente.

mcpServers[0].type string (opcional)

Tipo de transporte: http, sse ou stdio. Padrão: http para servidores remotos com url e stdio para servidores com command.

mcpServers[0].url string (obrigatório para MCP remoto)

URL HTTP ou HTTPS para um servidor MCP remoto. URLs com nome de usuário ou senha não são permitidas.

mcpServers[0].command string (obrigatório para MCP stdio)

Comando para iniciar um servidor MCP stdio dentro da VM do agente em nuvem. Use args e env para argumentos e segredos em tempo de execução.

customSubagents array (opcional)

Defina subagentes personalizados aos quais o agente principal pode delegar durante a execução. Máximo de 20 subagentes. Cada entrada exige name, description e prompt, além de um model opcional (string de ID do modelo, objeto ModelSelection ou "inherit"). Os nomes devem ser únicos e não podem conflitar com os incorporados (explore, debug, shell, computerUse, etc.).

mode string (opcional, padrão: agent)

Modo de conversa inicial para a primeira execução do agente. plan explora e elabora um plano antes de codificar (Modo de planejamento); agent implementa as alterações diretamente.

agentId string (opcional)

Identificador do agente fornecido pelo cliente no formato bc-<uuid>. Útil para fluxos de criação idempotentes — reenviar um POST com o mesmo agentId retorna 409 agent_id_conflict em vez de criar uma duplicata. Não pode ser combinado com envVars; omita agentId para que o servidor emita um quando você precisar de segredos de sessão.

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  }'

Pool de workers (incluindo qualquer repositório):

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

Resposta:

{  "agent": {    "id": "bc-00000000-0000-0000-0000-000000000001",    "name": "Adicionar README com instruções de configuração",    "status": "ACTIVE",    "env": {      "type": "cloud"    },    "repos": [      {        "url": "https://github.com/your-org/your-repo",        "startingRef": "main"      }    ],    "workOnCurrentBranch": false,    "autoCreatePR": true,    "url": "/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"  }}

Listar agentes

GET/v1/agents

Lista os agentes do usuário autenticado, do mais recente para o mais antigo.

Parâmetros de consulta

limit number (optional)

Número de agentes a retornar. Padrão: 20, Máx.: 100.

cursor string (optional)

Cherri Code de paginação obtido de nextCursor na resposta anterior.

prUrl string (optional)

Filtra agentes pela URL do pull request do GitHub.

includeArchived boolean (optional, default: true)

Indica se a resposta deve incluir agentes arquivados.

Os itens da lista incluem apenas os campos de identidade persistente. Chame GET /v1/agents/{id} para carregar o registro completo (repos, workOnCurrentBranch, autoCreatePR, etc.).

nextCursor é omitido da resposta quando não há mais páginas — ele não é retornado como null. Trate sua ausência como "não há mais resultados".

curl --request GET \  --url 'https://api.cursor.com/v1/agents?limit=20' \  -u YOUR_API_KEY:

Resposta:

{  "items": [    {      "id": "bc-00000000-0000-0000-0000-000000000001",      "name": "Add README with setup instructions",      "status": "ACTIVE",      "env": {        "type": "cloud"      },      "url": "/agents/bc-00000000-0000-0000-0000-000000000001",      "createdAt": "2026-04-13T18:30:00.000Z",      "updatedAt": "2026-04-13T18:45:00.000Z",      "latestRunId": "run-00000000-0000-0000-0000-000000000001"    }  ],  "nextCursor": "bc-00000000-0000-0000-0000-000000000002"}

Consultar um agente

GET/v1/agents/{id}

Recupere os metadados persistentes de um agente. O status de execução está nas execuções — consulte latestRunId e chame Obter uma execução para ver o estado da execução.

Parâmetros de caminho

id string

Identificador único do agente (por exemplo, bc-00000000-0000-0000-0000-000000000001).

Campo da resposta

status string

Status do ciclo de vida do agente. Os controladores o usam para decidir se uma máquina precisa permanecer ativa:

ACTIVE — Uma interação está em execução, aguardando trabalho em segundo plano ou prestes a iniciar. Mantenha a máquina do agente ativa.
IDLE — A última interação foi concluída e mensagens de acompanhamento são aceitas. A máquina do agente pode ser hibernada ou ter um snapshot criado. Execuções que terminaram com um erro recuperável também informam IDLE; os detalhes do erro no nível da execução permanecem em Obter uma execução.
ARCHIVED — O agente foi arquivado ou expirou. Estado terminal; as claims terminam e o estado do espaço de trabalho pode ser excluído.

curl --request GET \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001 \  -u YOUR_API_KEY:

Resposta:

{  "id": "bc-00000000-0000-0000-0000-000000000001",  "name": "Adicionar README com instruções de configuração",  "status": "ACTIVE",  "env": {    "type": "cloud"  },  "repos": [    {      "url": "https://github.com/your-org/your-repo",      "startingRef": "main"    }  ],  "workOnCurrentBranch": false,  "autoCreatePR": true,  "url": "/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"}

Criar uma execução

POST/v1/agents/{id}/runs

Envie um prompt de acompanhamento para um agente ativo existente. A nova execução usa a conversa e o estado atual do espaço de trabalho do agente.

Apenas uma execução pode ficar ativa por agente. Fazer essa chamada enquanto outra execução estiver CREATING ou RUNNING retorna 409 agent_busy. Aguarde a execução existente terminar ou cancele-a.

Parâmetros de caminho

id string

Identificador único do agente (por exemplo, bc-00000000-0000-0000-0000-000000000001).

Corpo da solicitação

prompt objeto (obrigatório)

O prompt de acompanhamento, incluindo imagens opcionais.

prompt.text string (obrigatório)

O texto da instrução do prompt de acompanhamento.

prompt.images matriz (opcional)

Entradas de imagem para o acompanhamento. Cada item deve incluir data (bytes codificados em base64 com mimeType obrigatório) ou url. No máximo 5 imagens, com 15 MB cada. Tipos MIME compatíveis: image/png, image/jpeg, image/gif, image/webp.

mcpServers matriz (opcional)

Definições inline de servidores MCP para esta execução de acompanhamento. Quando fornecidas, elas substituem quaisquer servidores MCP inline definidos no momento da criação para esta execução. Omita para manter a configuração MCP atual do agente.

mode string (opcional)

Substituição do modo de conversa para esta execução de acompanhamento: agent ou plan. Omita para manter o modo atual da conversa das execuções anteriores.

curl --request POST \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/runs \  -u YOUR_API_KEY: \  --header 'Content-Type: application/json' \  --data '{    "prompt": {      "text": "Also add troubleshooting steps"    },    "mcpServers": [      {        "name": "docs",        "type": "http",        "url": "https://example.com/mcp"      }    ]  }'

Resposta:

{  "run": {    "id": "run-00000000-0000-0000-0000-000000000002",    "agentId": "bc-00000000-0000-0000-0000-000000000001",    "status": "CREATING",    "createdAt": "2026-04-13T18:50:00.000Z",    "updatedAt": "2026-04-13T18:50:00.000Z"  }}

Listar execuções

GET/v1/agents/{id}/runs

Lista as execuções de um agente, da mais recente para a mais antiga.

Parâmetros de caminho

id string

Identificador único do agente.

Parâmetros de consulta

limit number (opcional)

Número de execuções a retornar. Padrão: 20, Máx.: 100.

cursor string (opcional)

Cherri Code de paginação de nextCursor da resposta anterior.

curl --request GET \  --url 'https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/runs?limit=20' \  -u YOUR_API_KEY:

Resposta:

{  "items": [    {      "id": "run-00000000-0000-0000-0000-000000000002",      "agentId": "bc-00000000-0000-0000-0000-000000000001",      "status": "RUNNING",      "createdAt": "2026-04-13T18:50:00.000Z",      "updatedAt": "2026-04-13T18:51:00.000Z",      "git": {        "branches": [          {            "repoUrl": "github.com/your-org/your-repo",            "branch": "cursor/add-readme-a1b2"          }        ]      }    }  ]}

Obter uma execução

GET/v1/agents/{id}/runs/{runId}

Recupera o status, os timestamps e, no caso de execuções de terminal, o resultado final, a duração e os branches enviados por push de uma execução específica.

Parâmetros de caminho

id string

Identificador único do agente.

runId string

Identificador único da execução (por exemplo, run-00000000-0000-0000-0000-000000000001).

Campos da resposta

Os campos base da execução (id, agentId, status, createdAt, updatedAt) estão sempre presentes. Os campos a seguir são preenchidos assim que os dados ficam disponíveis:

durationMs integer (execuções de terminal)

Duração total da execução em milissegundos, calculada quando a execução atinge FINISHED, ERROR, CANCELLED ou EXPIRED.

result string (execuções de terminal)

Texto da resposta final do assistente para uma execução encerrada.

git object (quando um branch foi enviado por push)

Os branches e pull requests atuais enviados por push pelo agente. git.branches[] contém entradas { repoUrl, branch?, prUrl? } — uma para cada branch enviado por push pelo agente (agentes empilhados geram vários).

Estado por agente, não por execução. Toda execução no mesmo agente retorna o mesmo snapshot de git. Use o latestRunId do agente ou o stream SSE para atribuir o trabalho a uma execução específica.

repoUrl é retornado sem o esquema (por exemplo, github.com/your-org/your-repo) — diferente de repos[].url da solicitação, que mantém o prefixo https://.

curl --request GET \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/runs/run-00000000-0000-0000-0000-000000000001 \  -u YOUR_API_KEY:

Resposta:

{  "id": "run-00000000-0000-0000-0000-000000000001",  "agentId": "bc-00000000-0000-0000-0000-000000000001",  "status": "FINISHED",  "createdAt": "2026-04-13T18:30:00.000Z",  "updatedAt": "2026-04-13T18:45:00.000Z",  "durationMs": 12357,  "result": "README.md adicionado com instruções de instalação e exemplos de uso.",  "git": {    "branches": [      {        "repoUrl": "github.com/your-org/your-repo",        "branch": "cursor/add-readme-a1b2",        "prUrl": "https://github.com/your-org/your-repo/pull/123"      }    ]  }}

Stream de uma execução

GET/v1/agents/{id}/runs/{runId}/stream

Transmite eventos SSE de uma execução. O stream é limitado à execução solicitada e não reproduz execuções anteriores.

Tipos de evento

status — atualização do status da execução. Payload: { runId, status }.
assistant — delta de texto do assistente. Payload: { text }.
thinking — delta de texto de raciocínio. Payload: { text }.
tool_call — atualização do status da chamada de ferramenta. Payload: { callId, name, status, args?, result?, truncated? }.
interaction_update — evento opcional mais detalhado emitido junto com os eventos simplificados acima. O payload corresponde ao formato InteractionUpdate consumido pelo TypeScript SDK, com subtipos como text-delta, tool-call-started / tool-call-completed, step-started / step-completed e turn-ended. Se você só precisa de texto simples e chamadas de ferramenta, processe os eventos simplificados e ignore interaction_update. Se quiser o stream completo no formato do SDK, processe interaction_update e ignore os eventos simplificados.
heartbeat — evento de keepalive. Payload: {}.
result — status terminal da execução. Payload: { runId, status, text?, durationMs?, git? }. text é a resposta final do assistente, durationMs é a duração total da execução em milissegundos, e git espelha Run.git (os branches atuais enviados por push pelo agente, não apenas os desta execução).
error — erro do stream. Payload: { code, message }.
done — stream concluído. Payload: {}.

Payloads de chamada de ferramenta

Os eventos tool_call usam um envelope estável para entradas e saídas específicas da ferramenta:

type JsonValue =  | string  | number  | boolean  | null  | JsonValue[]  | { [key: string]: JsonValue };interface ToolCallEventData {  callId: string;  name: string;  status: "running" | "completed";  args?: JsonValue;  result?: JsonValue;  truncated?: {    args?: true;    result?: true;  };}

callId identifica uma invocação de ferramenta ao longo das atualizações. name é o nome público da ferramenta, como read_file, run_terminal_cmd ou mcp. args e result são valores JSON específicos da ferramenta. Se args ou result for grande demais para incluir no stream, o Cherri Code omite esse campo e define a flag truncated correspondente.

Retomando um stream

A maioria dos eventos inclui uma linha id — uma string opaca que você não deve analisar (o formato atual se parece com 1713033006000-0, mas trate-a como opaca). O evento status inicial não tem id — é um evento de enquadramento sticky, reenviado no início de cada reconexão.

Para retomar após uma desconexão, reconecte com Last-Event-ID definido como o id do evento recebido mais recentemente. O id do evento deve pertencer à execução solicitada; caso contrário, a solicitação retorna 400 invalid_last_event_id. Após uma retomada bem-sucedida, espere outro evento status antes de o intervalo retomado começar.

Retenção

As respostas do stream incluem o cabeçalho X-Cursor-Stream-Retention-Seconds. Após o término da janela de retenção, este endpoint pode retornar 410 stream_expired. Trate isso como um sinal para consultar o estado terminal via Obter uma execução, em vez de tentar novamente o stream.

curl --request GET \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/runs/run-00000000-0000-0000-0000-000000000001/stream \  -u YOUR_API_KEY: \  --header 'Accept: text/event-stream'

Exemplo de stream:

event: statusdata: {"runId":"run-00000000-0000-0000-0000-000000000001","status":"RUNNING"}id: 1713033000000-0event: assistantdata: {"text":"I'll update the README now."}id: 1713033005000-0event: tool_calldata: {"callId":"call-1","name":"read_file","status":"running","args":{"path":"README.md"}}id: 1713033006000-0event: tool_calldata: {"callId":"call-1","name":"read_file","status":"completed","args":{"path":"README.md"},"result":{"success":{"content":"# Project","totalLines":1,"fileSize":9,"path":"README.md"}}}id: 1713033010000-0event: resultdata: {"runId":"run-00000000-0000-0000-0000-000000000001","status":"FINISHED","text":"Added README.md with installation instructions.","durationMs":12357,"git":{"branches":[{"repoUrl":"github.com/your-org/your-repo","branch":"cursor/add-readme-a1b2"}]}}id: 1713033010000-0event: donedata: {}

Cancelar uma execução

POST/v1/agents/{id}/runs/{runId}/cancel

Cancela a execução ativa de um agente. O cancelamento é definitivo — a execução passa para CANCELLED e não pode ser retomada. Para continuar a conversa, crie uma nova execução no mesmo agente.

Cancelar uma execução que já está em estado terminal, ou que nunca esteve ativa, retorna 409 run_not_cancellable.

Parâmetros de caminho

id string

Identificador único do agente.

runId string

Identificador único da execução a ser cancelada.

curl --request POST \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/runs/run-00000000-0000-0000-0000-000000000001/cancel \  -u YOUR_API_KEY:

Resposta:

{  "id": "run-00000000-0000-0000-0000-000000000001"}

Consultar uso do agente

GET/v1/agents/{id}/usage

Recupera o uso de tokens de um agente, detalhado por execução. A resposta soma o uso em todas as execuções do agente e lista o uso de cada execução individual. O uso de tokens segue o tokenUsage informado pelo endpoint de eventos de uso da equipe.

Parâmetros de caminho

id string

Identificador único do agente (por exemplo, bc-00000000-0000-0000-0000-000000000001).

Parâmetros de consulta

runId string (optional)

Limita a resposta a uma única execução (por exemplo, run-00000000-0000-0000-0000-000000000001). Omita esse parâmetro para retornar o uso de todas as execuções do agente. Um runId desconhecido retorna 404 run_not_found.

Campos da resposta

totalUsage object

Uso de tokens somado em todas as execuções retornadas. Contém os mesmos campos do objeto usage de cada execução.

runs array

Uso por execução, com uma entrada por execução (ou uma única entrada quando runId está definido). Cada objeto contém:

id string - Identificador da execução (por exemplo, run-00000000-0000-0000-0000-000000000001).
usageUuid string (optional) - Identificador interno de uso da execução. Omitido quando a execução ainda não tem uso registrado.
usage object - Uso de tokens desta execução:
- inputTokens number - Tokens de entrada consumidos.
- outputTokens number - Tokens de saída gerados.
- cacheWriteTokens number - Tokens gravados no cache.
- cacheReadTokens number - Tokens lidos do cache.
- totalTokens number - Soma das quatro contagens de tokens acima.

Execuções sem nenhum uso de tokens registrado informam zero em todos os campos. Uma execução que ainda não gerou uso continua aparecendo em runs, para que você possa rastreá-la ao longo do tempo.

# Todas as execuções no agentecurl --request GET \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/usage \  -u YOUR_API_KEY:# Uma única execuçãocurl --request GET \  --url 'https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/usage?runId=run-00000000-0000-0000-0000-000000000001' \  -u YOUR_API_KEY:

Resposta:

{  "totalUsage": {    "inputTokens": 12480,    "outputTokens": 3110,    "cacheWriteTokens": 18200,    "cacheReadTokens": 42600,    "totalTokens": 76390  },  "runs": [    {      "id": "run-00000000-0000-0000-0000-000000000002",      "usageUuid": "00000000-0000-0000-0000-000000000002",      "usage": {        "inputTokens": 6320,        "outputTokens": 1450,        "cacheWriteTokens": 7100,        "cacheReadTokens": 21300,        "totalTokens": 36170      }    },    {      "id": "run-00000000-0000-0000-0000-000000000001",      "usageUuid": "00000000-0000-0000-0000-000000000001",      "usage": {        "inputTokens": 6160,        "outputTokens": 1660,        "cacheWriteTokens": 11100,        "cacheReadTokens": 21300,        "totalTokens": 40220      }    }  ]}

Artefatos

Os artefatos são vinculados ao agente porque o espaço de trabalho persiste entre execuções.

Listar artefatos

GET/v1/agents/{id}/artifacts

Lista os artefatos gerados por um agente. O path de cada artefato é relativo ao diretório artifacts/ do espaço de trabalho.

Passe o valor de path retornado aqui diretamente para Baixar um artefato. Os caminhos da v1 são relativos; caminhos absolutos da v0 (/opt/cursor/artifacts/...) não são aceitos.

Parâmetros de caminho

id string

Identificador único do agente.

curl --request GET \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/artifacts \  -u YOUR_API_KEY:

Resposta:

{  "items": [    {      "path": "artifacts/screenshot.png",      "sizeBytes": 12345,      "updatedAt": "2026-04-13T18:45:00.000Z"    }  ]}

Baixar um artefato

GET/v1/agents/{id}/artifacts/download

Retorna uma URL S3 temporária pré-assinada, válida por 15 minutos, para um artefato específico.

Parâmetros de caminho

id string

Identificador único do agente.

Parâmetros de consulta

path string

Caminho relativo do artefato retornado por Listar artefatos (por exemplo, artifacts/screenshot.png). Deve estar em artifacts/.

curl --request GET \  --url 'https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/artifacts/download?path=artifacts/screenshot.png' \  -u YOUR_API_KEY:

Resposta:

{  "url": "https://cloud-agent-artifacts.s3.us-east-1.amazonaws.com/...",  "expiresAt": "2026-04-13T19:00:00.000Z"}

Ciclo de vida do agente

Arquivar um agente

POST/v1/agents/{id}/archive

Arquive um agente. Agentes arquivados continuam legíveis, mas não podem aceitar novas execuções até serem desarquivados. Use isso em fluxos reversíveis de "exclusão suave".

Arquivar é idempotente — arquivar novamente um agente já arquivado retorna 200 sem alteração. Você não precisa verificar o estado atual antes de chamar.

Parâmetros de caminho

id string

Identificador único do agente.

curl --request POST \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/archive \  -u YOUR_API_KEY:

Resposta:

{  "id": "bc-00000000-0000-0000-0000-000000000001"}

Desarquivar um agente

POST/v1/agents/{id}/unarchive

Desarquive um agente para que ele volte a aceitar novas execuções.

Desarquivar é idempotente — chamá-lo em um agente já ativo retorna 200 sem alteração.

Parâmetros de caminho

id string

Identificador único do agente.

curl --request POST \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/unarchive \  -u YOUR_API_KEY:

Resposta:

{  "id": "bc-00000000-0000-0000-0000-000000000001"}

Excluir um agente permanentemente

DELETE/v1/agents/{id}

Exclua permanentemente um agente. Esta ação é irreversível. Use Arquivar para uma exclusão reversível.

Parâmetros de caminho

id string

Identificador único do agente.

curl --request DELETE \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001 \  -u YOUR_API_KEY:

Resposta:

{  "id": "bc-00000000-0000-0000-0000-000000000001"}

Tokens de worker

Criar um token de worker com escopo de usuário

POST/v1/sub-tokens

Crie um token com escopo de usuário com duração de uma hora para um worker ser executado como um membro ativo da equipe.

Requer uma chave de API de conta de serviço da equipe com escopo de agente. Tokens com escopo de usuário não podem gerar outros tokens com escopo de usuário.

O token retornado expira após 1 hora e não pode ser renovado automaticamente. Gere um novo token com a chave de API da conta de serviço quando precisar renovar o token de um worker em execução.

Corpo da solicitação

Especifique exatamente um dos itens a seguir para identificar o usuário de destino:

forUserEmail string (opcional)

Email do membro ativo da equipe. Não diferencia maiúsculas de minúsculas.

forUserId integer (opcional)

ID numérico de usuário do Cherri Code do membro ativo da equipe.

Por email:

curl --request POST \  --url https://api.cursor.com/v1/sub-tokens \  --header "Authorization: Bearer $CURSOR_SERVICE_ACCOUNT_API_KEY" \  --header "Content-Type: application/json" \  --data '{    "forUserEmail": "[email protected]"  }'

Por ID de usuário:

curl --request POST \  --url https://api.cursor.com/v1/sub-tokens \  --header "Authorization: Bearer $CURSOR_SERVICE_ACCOUNT_API_KEY" \  --header "Content-Type: application/json" \  --data '{    "forUserId": 42  }'

Resposta:

{  "accessToken": "eyJ...",  "expiresAt": "2026-04-24T19:00:00.000Z",  "userId": 42,  "teamId": 456}

Workers e Pools

Monitore a utilização dos workers e implemente autoscaling para seus pools. Pools duráveis permanecem registrados após a desconexão do último worker, permitindo reduzir a escala a zero e restaurar a capacidade quando surgirem solicitações pendentes.

Os caminhos de endpoint mantêm o nome antigo private-workers; eles se referem aos mesmos workers de Self-Hosted Machines.

Autentique-se com a chave de API da conta de serviço do pool via Basic auth ou Bearer token. Outros tipos de chave de API são rejeitados.

Listar workers

GET/v0/private-workers

Lista os workers do pool da equipe da conta de serviço autenticada, do mais recente ao mais antigo.

Parâmetros de consulta

status string (opcional, padrão: all)

Filtra por status do worker. Valores possíveis: all, in_use ou idle.

scope string (opcional, padrão: all)

Filtra por escopo do worker. Valores possíveis: all, team_pool ou personal.

limit integer (opcional, padrão: 50)

Resultados por página. Intervalo: de 1 a 100.

pageToken string (opcional)

Cherri Code de paginação. Informe o nextPageToken da resposta anterior.

Campos da resposta

workers array

Workers conectados. Cada item inclui:

workerId string — Identificador exclusivo do worker. IDs gerados automaticamente são UUIDs; workers iniciados com CURSOR_AGENT_WORKER_ID informam esse ID personalizado.
isInUse boolean — Indica se o worker tem um agente atribuído no momento.
repoOwner, repoName string — Metadados do repositório principal quando o worker registrou um remote do Git. Strings vazias para workers com qualquer repositório.
repoUrl string (opcional) — URL do repositório principal. Omitido para workers com qualquer repositório.
workspaceRootPath string — Caminho do espaço de trabalho principal no worker.
connectedAtMs integer — Horário da conexão em milissegundos Unix.
userId integer — ID do usuário proprietário. 0 para workers autenticados com uma chave de conta de serviço.
teamId integer (opcional) — ID da equipe para workers do pool da equipe.
serviceAccountId string (opcional) — Conta de serviço que autenticou o worker.
activeBcId string (opcional) — ID do agente em execução no worker, quando estiver em uso.
name string (opcional) — Nome de exibição do worker (--name, o valor padrão é o hostname da máquina).

totalCount integer

Total de workers que correspondem ao filtro em todas as páginas.

nextPageToken string (opcional)

Cherri Code de paginação para pageToken. Omitido quando não há mais páginas.

curl --request GET \  --url "https://api.cursor.com/v0/private-workers?status=idle&scope=team_pool&limit=50" \  -u "$CURSOR_API_KEY:"

Resposta:

{  "workers": [    {      "workerId": "a8574fe8-248e-424a-a078-7584a2b93724",      "repoOwner": "acme",      "repoName": "payments-service",      "repoUrl": "https://github.com/acme/payments-service",      "workspaceRootPath": "/home/agent/payments-service",      "connectedAtMs": 1737306880000,      "userId": 0,      "teamId": 456,      "serviceAccountId": "sa_abc123",      "isInUse": false,      "name": "gpu-worker-1"    }  ],  "totalCount": 1}

Obter resumo do worker

GET/v0/private-workers/summary

Retorna o número de workers conectados e em uso para o usuário autenticado e sua equipe. Use isso para acionar decisões de escalonamento quando a utilização estiver alta.

curl --request GET \  --url "https://api.cursor.com/v0/private-workers/summary" \  -u "$CURSOR_API_KEY:"

Exemplo de verificação de escalonamento:

const summary = await response.json();const team = summary.teamSummary;if (team && team.totalConnected > 0) {  const utilization = team.inUse / team.totalConnected;  if (utilization >= 0.9) {    // Aumentar a escala: provisionar workers adicionais  }}

Obter worker por ID

GET/v0/private-workers/{id}

Recupere um worker específico do pool pelo ID.

Parâmetros de caminho

id string

Identificador único do worker (por exemplo, pw_123).

curl --request GET \  --url "https://api.cursor.com/v0/private-workers/pw_123" \  -u "$CURSOR_API_KEY:"

Listar pools

GET/v0/private-workers/pools

Liste pools duráveis da equipe da conta de serviço autenticada. Os pools permanecem registrados após a desconexão do último worker, permitindo monitorar pools de workers escalados para zero e decidir quando provisionar capacidade.

Parâmetros de consulta

scope string (opcional)

Filtre pelo escopo da lista de pools. Pode ser all, team_pool ou personal.

includeStale boolean (opcional, padrão: false)

Quando true, inclui pools marcados como inativos após um longo período sem atividade.

Campos da resposta

pools matriz

Pools registrados. Cada entrada inclui:

scope string — Escopo de propriedade do pool (user ou team).
ownerId integer — ID do usuário ou da equipe proprietária no escopo.
poolName string — Nome do pool (por exemplo, default ou gpu).
connectedWorkerCount integer — Workers atualmente conectados a este pool.
inUseWorkerCount integer — Workers conectados que têm um agente atribuído no momento. A capacidade ociosa é connectedWorkerCount - inUseWorkerCount.
firstSeenAtMs, lastSeenAtMs integer — Horários da primeira e da última observação em milissegundos Unix.
isStale boolean — Indica se o pool está marcado como inativo após um longo período sem atividade.
repoOwner, repoName, repoUrl string (opcional) — Metadados do repositório quando o pool está vinculado a um repositório. Omitidos para pools de qualquer repositório.
workerReadyTimeoutSeconds integer — Segundos que uma solicitação reservada aguarda o worker desconectado deste pool se reconectar antes que a reserva expire. 0 significa que as mensagens de acompanhamento de um worker desconectado voltam a buscar um worker no pool imediatamente.

curl --request GET \  --url "https://api.cursor.com/v0/private-workers/pools?scope=team_pool&includeStale=false" \  -u "$CURSOR_API_KEY:"

Resposta:

{  "pools": [    {      "scope": "team",      "ownerId": 456,      "poolName": "gpu",      "repoOwner": "acme",      "repoName": "payments-service",      "repoUrl": "https://github.com/acme/payments-service",      "connectedWorkerCount": 2,      "inUseWorkerCount": 1,      "firstSeenAtMs": 1737000000000,      "lastSeenAtMs": 1737306880000,      "isStale": false,      "workerReadyTimeoutSeconds": 900    },    {      "scope": "team",      "ownerId": 456,      "poolName": "sandbox",      "connectedWorkerCount": 0,      "inUseWorkerCount": 0,      "firstSeenAtMs": 1737100000000,      "lastSeenAtMs": 1737200000000,      "isStale": false,      "workerReadyTimeoutSeconds": 0    }  ]}

A entrada sandbox é de qualquer repositório: os campos de repositório são omitidos, e o pool continua selecionável mesmo sem workers conectados.

Registrar um pool

POST/v0/private-workers/pools

Registre um pool durável sem iniciar um worker. Use esta opção para disponibilizar um pool para seleção antes que qualquer worker se conecte, por exemplo, quando um controlador provisiona capacidade sob demanda. Iniciar um worker com --pool registra o pool automaticamente; este endpoint só é necessário para criar o pool antecipadamente.

Corpo da solicitação

scope string (obrigatório)

Escopo de propriedade do pool. Pode ser user ou team.

poolName string (obrigatório)

Nome do pool a registrar (por exemplo, gpu).

repoOwner, repoName string (opcional)

Metadados do repositório quando o pool está vinculado a um repositório. Informe ambos ou omita ambos para um pool de qualquer repositório.

repoUrl string (opcional)

URL do repositório para exibição. Requer repoOwner e repoName.

workerReadyTimeoutSeconds integer (opcional, padrão: 0)

Número de segundos que uma solicitação reservada aguarda a reconexão de um worker desconectado deste pool antes que a reserva expire e a solicitação volte para a fila. Defina isso quando as máquinas hibernam entre turnos e podem ser reativadas. Com 0, as mensagens de acompanhamento de um worker desconectado voltam a buscar um worker no pool imediatamente. Deve ser um integer não negativo.

Campos da resposta

registered boolean

Indica se o pool foi registrado.

curl --request POST \  --url "https://api.cursor.com/v0/private-workers/pools" \  -u "$CURSOR_API_KEY:" \  --header 'Content-Type: application/json' \  --data '{    "scope": "team",    "poolName": "payments-pool",    "repoOwner": "acme",    "repoName": "payments-service",    "repoUrl": "https://github.com/acme/payments-service"  }'

Resposta:

{  "registered": true}

Remover o Registro de um Pool

DELETE/v0/private-workers/pools

Remova o registro (exclusão lógica) de um pool durável para que ele não apareça mais nos seletores de pool nem em Listar Pools. Os workers atualmente conectados ao pool não são afetados. Pools de equipe exigem um administrador da equipe; pools de usuário exigem seu proprietário.

Parâmetros de consulta

scope string (obrigatório)

Escopo de propriedade do pool. user ou team.

pool_name string (obrigatório)

Nome do pool cujo registro será removido.

repo_owner string (opcional)

Proprietário do repositório ao remover o registro de um pool com escopo de repositório.

repo_name string (opcional)

Nome do repositório ao remover o registro de um pool com escopo de repositório. Informe repo_owner e repo_name juntos ou omita ambos para um pool de qualquer repositório.

curl --request DELETE \  --url "https://api.cursor.com/v0/private-workers/pools?scope=team&pool_name=sandbox" \  -u "$CURSOR_API_KEY:"

Resposta:

{  "deregistered": true}

Listar solicitações pendentes do pool

GET/v0/private-workers/pending-requests

Liste solicitações de pool que ainda não foram atribuídas a um worker. Use este endpoint para aumentar a capacidade quando usuários estiverem aguardando um worker do pool disponível ou combine-o com Reivindicar uma solicitação pendente antes de iniciar um worker efêmero.

Para pools configurados com workerReadyTimeoutSeconds, a listagem também exibe entradas reivindicadas, mas offline: solicitações cujo worker reivindicado está offline enquanto há uma janela de reconexão aberta. Essas entradas trazem claimedWorkerId e wakeTimeoutMs para que um controlador possa reativar a máquina.

Este endpoint exige uma chave de API de conta de serviço. Ele retorna solicitações da equipe associada à chave e exclui solicitações do My Machines. Se a chave tiver escopo limitado a repositórios específicos, informe repository; o repositório deve estar no escopo permitido da chave.

A resposta inclui um streamCursor. Passe-o para Monitorar solicitações pendentes do pool para acompanhar alterações na fila em tempo real após este snapshot.

Parâmetros de consulta

limit número (opcional)

Número de solicitações pendentes a retornar. Padrão: 50, Máximo: 100.

pageToken string (opcional)

Cherri Code de paginação da resposta anterior. Os tokens de página estão vinculados aos filtros repository e pool que os emitiram.

repository string (opcional)

Filtre por URL do repositório. Obrigatório para chaves de API de conta de serviço com escopo de repositório. Omita para solicitações pendentes de qualquer repositório.

pool string (opcional)

Filtre pelo nome do pool. Correspondência exata, diferenciando maiúsculas de minúsculas, com o rótulo pool da solicitação. Omita para listar solicitações de todos os pools da equipe.

Campos de resposta

requests matriz

Solicitações pendentes. Cada entrada inclui:

id string — ID da solicitação pendente ou do agente (passe para Reivindicar ou Liberar uma reserva como id).
userId integer — ID do usuário do Cherri Code que criou a solicitação.
userEmail string (opcional) — E-mail do usuário solicitante, quando disponível. Use-o para selecionar capacidade associada ao usuário sem fazer outra consulta.
serviceAccountId string (opcional) — Conta de serviço associada à solicitação, quando presente.
repoOwner, repoName, repoUrl string (opcional) — Metadados do repositório quando a solicitação é destinada a um repositório. Omitidos para solicitações de pool de qualquer repositório.
labels matriz — Rótulos da solicitação como pares { key, value } (inclui repo= e pool= quando definidos).
createdAtMs integer — Horário de criação da solicitação em milissegundos Unix.
claimedWorkerId string (opcional) — Presente em entradas reivindicadas, mas offline: a solicitação foi reivindicada por este worker, que está offline no momento. Inicie um worker com este ID (CURSOR_AGENT_WORKER_ID) para retomar o agente na máquina dele.
wakeTimeoutMs integer (opcional) — Milissegundos restantes na janela de reconexão de uma entrada reivindicada, mas offline. Quando a janela expira, a reivindicação expira e a solicitação é anunciada novamente como uma entrada não reivindicada.

nextPageToken string (opcional)

Cherri Code de paginação. Omitido quando não há mais páginas. Para medir o tamanho da fila, pagine até o fim e conte as solicitações.

streamCursor string

Posição opaca para retomar o acompanhamento em Monitorar solicitações pendentes do pool. Todas as páginas de uma mesma listagem repetem o mesmo streamCursor; inicie o monitoramento a partir dele após concluir a paginação. Ele expira cinco minutos após a listagem que o emitiu.

curl --request GET \  --url "https://api.cursor.com/v0/private-workers/pending-requests?limit=50&repository=https%3A%2F%2Fgithub.com%2Facme%2Fpayments-service" \  -u "$CURSOR_API_KEY:"

Resposta:

{  "requests": [    {      "id": "bc-00000000-0000-0000-0000-000000000002",      "userId": 321,      "userEmail": "[email protected]",      "serviceAccountId": "sa_abc123",      "repoOwner": "acme",      "repoName": "payments-service",      "repoUrl": "https://github.com/acme/payments-service",      "labels": [        { "key": "repo", "value": "acme/payments-service" },        { "key": "pool", "value": "gpu" },        { "key": "env", "value": "production" }      ],      "createdAtMs": 1737306880000    }  ],  "nextPageToken": "eyJjcmVhdGVkQXRNcyI6MTczNzMwNjg4MDAwMH0=",  "streamCursor": "djQuZXhhbXBsZS1vcGFxdWUtY3Vyc29y"}

repoUrl omite credenciais incorporadas quando a URL original do repositório contém userinfo.

Monitorar Solicitações Pendentes do Pool

GET/v0/private-workers/pending-requests/stream

Receba eventos do ciclo de vida de solicitações pendentes via eventos enviados pelo servidor (SSE), para que os controladores possam reagir a alterações na fila sem fazer polling.

Este endpoint exige uma chave de API da conta de serviço. Os controladores primeiro listam e depois monitoram: chame Listar Solicitações Pendentes do Pool para montar sua visualização da fila, guarde o streamCursor da resposta e abra o monitoramento exatamente dessa posição. Use os mesmos filtros de repository e pool na lista e no monitoramento; os cursores são vinculados aos filtros que os emitiram.

Parâmetros de consulta

cursor string (obrigatório)

O streamCursor de uma resposta de listagem ou o id: SSE do último evento processado. Ao reconectar, um EventSource nativo reenvia esse ID como o cabeçalho Last-Event-ID, que tem precedência sobre o parâmetro de consulta.

repository string (opcional)

Tem a mesma semântica de Listar Solicitações Pendentes do Pool. Obrigatório para chaves de API de contas de serviço com escopo de repositório. Parâmetros de paginação não são aceitos no stream.

pool string (opcional)

Monitore apenas eventos deste pool. A correspondência é exata e diferencia maiúsculas de minúsculas em relação ao rótulo pool da solicitação. Deve corresponder ao filtro usado na listagem que emitiu o cursor. Omita para monitorar todos os pools da equipe.

Eventos

O monitoramento reproduz as transições retidas após o cursor e, em seguida, acompanha os eventos em tempo real. O id: SSE de cada evento é o cursor a ser usado para retomar caso a conexão caia.

created evento — Uma solicitação entrou na fila, incluindo uma solicitação assumida, mas offline, cuja janela de reconexão se encerrou e cuja atribuição expirou. Payload: o mesmo objeto de solicitação de Listar Solicitações Pendentes do Pool.
claimed evento — Um worker assumiu a solicitação ou um worker off-line se reconectou e retomou a solicitação que havia assumido. Payload: { id }.
claimed_offline evento — Uma mensagem de acompanhamento chegou para uma solicitação cujo worker atribuído está offline. Payload: o mesmo objeto de solicitação de Listar Solicitações Pendentes do Pool, incluindo claimedWorkerId e wakeTimeoutMs. Reative a máquina antes que a janela expire, ou a atribuição expira e a solicitação é anunciada novamente com um novo evento created.
expired evento — A solicitação saiu da fila sem ser assumida. Payload: { id }.
heartbeat evento — Checkpoint do cursor sem alteração de estado, enviado aproximadamente a cada 20 segundos em um stream sem atividade. Payload: {}. Os heartbeats avançam a posição de retomada de um monitoramento inativo, mas não estendem a validade do cursor.

Tempo de vida do cursor

Cada cursor em uma cadeia de monitoramento expira cinco minutos após a listagem que o emitiu. Heartbeats e reconexões não estendem esse prazo. Quando o cursor expira ou a janela de eventos retidos deixa de cobri-lo, o endpoint retorna HTTP 410 Gone com {"code": "cursor_expired"}: faça uma nova listagem e monitore a partir do novo streamCursor. Isso é esperado, não é um caminho de erro. Faça novas listagens proativamente em um temporizador de cinco minutos com variação aleatória, em vez de aguardar o 410, para que um pool de workers de controladores não sincronize suas chamadas de listagem.

Garantias de entrega

A entrega é por melhor esforço, e a listagem é a fonte da verdade. Os eventos são publicados após a confirmação de cada transição, com novas tentativas, mas uma falha rara pode fazer com que um evento seja perdido, e um evento perdido nunca é reenviado. Entre novas listagens, trate os eventos como sinais de baixa latência: aplique-os de forma idempotente (faça upsert das solicitações created e claimed_offline e remova as solicitações claimed e expired por id) e deixe que a próxima listagem corrija qualquer divergência. Um evento claimed para uma solicitação que você nunca viu não tem efeito. As atribuições permanecem atômicas no servidor, independentemente da sua visualização local.

Não persista cursores. Uma conta de serviço pode manter no máximo quatro streams simultâneos; use um stream por controlador e distribua os eventos localmente.

curl --request GET --no-buffer \  --url "https://api.cursor.com/v0/private-workers/pending-requests/stream?cursor=$STREAM_CURSOR" \  --header 'Accept: text/event-stream' \  -u "$CURSOR_API_KEY:"

Exemplo de stream:

: connected

event: heartbeat
id: djQuY3Vyc29yLWNoZWNrcG9pbnQ
data: {}

event: created
id: djQuY3Vyc29yLWFmdGVyLWNyZWF0ZWQ
data: {"id":"bc-00000000-0000-0000-0000-000000000002","userId":321,"userEmail":"[email protected]","repoOwner":"acme","repoName":"payments-service","repoUrl":"https://github.com/acme/payments-service","labels":[{"key":"pool","value":"gpu"}],"createdAtMs":1737306880000}

event: claimed
id: djQuY3Vyc29yLWFmdGVyLWNsYWltZWQ
data: {"id":"bc-00000000-0000-0000-0000-000000000002"}

O loop do controlador:

Liste as solicitações pendentes até a conclusão e substitua sua visualização local pelo resultado. Mantenha o streamCursor da resposta.
Abra o monitoramento com ?cursor=<streamCursor> e aplique os eventos à sua visualização local. Rastreie o id: do evento mais recente que você processou.
Em caso de desconexão, reconecte-se usando o id do evento mais recente como ?cursor=, ou use um EventSource nativo, que o reenvia automaticamente como Last-Event-ID.
Ao receber HTTP 410 Gone, volte à etapa 1 e liste novamente.

Reservar uma solicitação pendente

POST/v0/private-workers/claim

Reserve uma solicitação de pool pendente para um worker específico antes de iniciá-lo. Os controladores usam esta operação para atribuir trabalho de forma atômica entre réplicas: leem as solicitações pendentes, reservam uma e iniciam um worker com um ID estável que corresponda à reserva.

Uma segunda reserva enquanto houver uma reserva ativa é rejeitada. Libere uma reserva primeiro e, depois, reserve um novo workerId.

Este endpoint requer uma chave de API de conta de serviço.

Corpo da solicitação

id string (obrigatório)

ID da solicitação pendente. Mesmo valor de id em Listar solicitações pendentes do pool.

workerId string (obrigatório)

ID do worker a ser reservado para a solicitação. Inicie o worker com o mesmo ID usando CURSOR_AGENT_WORKER_ID (ou a flag oculta --worker-id) para que a ponte registre a identidade reservada.

sessionToken boolean (opcional, padrão: false)

Também emite um token de sessão para esta reserva, para que o worker possa ser iniciado sem a chave da conta de serviço. Se não for possível emitir o token, a reserva falha e a solicitação permanece não reservada.

Campos de resposta

id, workerId string

A solicitação reservada e o ID do worker.

token string (opcional)

Token de sessão válido apenas para esta reserva. Presente quando a solicitação enviou sessionToken: true. Ele deixa de funcionar quando a reserva é liberada ou quando a chave de API que o emitiu é excluída ou expira.

expiresAt string (opcional)

Timestamp ISO 8601, 7 dias após a emissão. Presente junto com token.

curl --request POST \  --url "https://api.cursor.com/v0/private-workers/claim" \  -u "$CURSOR_API_KEY:" \  --header 'Content-Type: application/json' \  --data '{    "id": "bc-00000000-0000-0000-0000-000000000002",    "workerId": "pw_123"  }'

Resposta:

{  "id": "bc-00000000-0000-0000-0000-000000000002",  "workerId": "pw_123"}

Após reservar a solicitação, inicie o worker com o ID reservado:

export CURSOR_API_KEY="your-service-account-api-key"export CURSOR_AGENT_WORKER_ID="pw_123"agent worker --pool gpu --worker-dir /workspace start

Com um token de sessão:

curl --request POST \  --url "https://api.cursor.com/v0/private-workers/claim" \  -u "$CURSOR_API_KEY:" \  --header 'Content-Type: application/json' \  --data '{    "id": "bc-00000000-0000-0000-0000-000000000002",    "workerId": "pw_123",    "sessionToken": true  }'

Resposta:

{  "id": "bc-00000000-0000-0000-0000-000000000002",  "workerId": "pw_123",  "token": "eyJ...",  "expiresAt": "2026-10-02T21:00:00.000Z"}

Inicie o worker com o token em vez da chave:

printf '%s' "$TOKEN" > /run/cursor/tokenexport CURSOR_AGENT_WORKER_ID="pw_123"agent worker --pool gpu --worker-dir /workspace --auth-token-file /run/cursor/token start

Criar um token de sessão

POST/v0/private-workers/tokens

Emite um token de sessão para uma declaração que sua equipe já detém. Use-o quando um worker se reconectar a uma declaração existente, como no caso de uma máquina hibernada que foi reativada, ou quando uma execução durar mais que o próprio token. agent worker controller --session-token chama este endpoint automaticamente ao despertar uma máquina hibernada.

O token vale apenas para esta declaração. Ele deixa de funcionar quando a declaração é liberada ou quando a chave de API que o emitiu é excluída ou expira.

Este endpoint exige uma chave de API de conta de serviço com escopo de agente, pertencente à equipe que detém a declaração. Uma chave com escopo de repositório só pode emitir tokens para agentes em repositórios dentro do seu escopo.

Corpo da solicitação

id string (obrigatório)

ID do agente ao qual a declaração se refere. Mesmo valor de id em Reservar uma solicitação pendente.

workerId string (obrigatório)

ID do worker que a declaração vincula ao agente.

curl --request POST \  --url "https://api.cursor.com/v0/private-workers/tokens" \  -u "$CURSOR_API_KEY:" \  --header 'Content-Type: application/json' \  --data '{    "id": "bc-00000000-0000-0000-0000-000000000002",    "workerId": "pw_123"  }'

Resposta:

{  "id": "bc-00000000-0000-0000-0000-000000000002",  "workerId": "pw_123",  "token": "eyJ...",  "expiresAt": "2026-10-02T21:00:00.000Z"}

HTTP 404 significa que sua equipe não detém nenhuma declaração que vincule esse worker a esse agente.

Liberar uma reserva

POST/v0/private-workers/claims/{id}/release

Remove a reivindicação de longo prazo que vincula um agente a um worker self-hosted. Após a liberação, o Cherri Code deixa de priorizar essa máquina para o agente.

A reivindicação é uma sugestão de roteamento, não o estado de um processo em execução. A liberação não verifica se o worker está conectado. Uma mensagem de acompanhamento pendente retorna à fila do pool no próximo ponto de agendamento. Um worker conectado conclui seu turno atual sem interrupções. Um worker substituto pode reivindicar o mesmo agente imediatamente após a liberação.

Uma segunda Reservar uma solicitação pendente enquanto houver uma reivindicação ativa será rejeitada. Libere-a primeiro e, em seguida, reivindique um novo workerId.

--idle-release-timeout (var. de ambiente CURSOR_WORKER_IDLE_RELEASE_TIMEOUT) faz a CLI do worker encerrar após ficar ociosa. Este endpoint apenas remove a reivindicação de roteamento.

Este endpoint requer uma chave de API de conta de serviço.

Parâmetros de caminho

id string

ID da solicitação pendente / agente. Mesmo valor de id em Reservar uma solicitação pendente. Sem corpo da solicitação.

curl --request POST \  --url "https://api.cursor.com/v0/private-workers/claims/bc-00000000-0000-0000-0000-000000000002/release" \  -u "$CURSOR_API_KEY:"

Resposta:

{  "id": "bc-00000000-0000-0000-0000-000000000002",  "workerId": "pw_123"}

HTTP 404 significa que não há uma reivindicação ativa: ela já foi liberada, expirou ou foi adotada. Não tente novamente após um 404.

Endpoints de metadados

Informações da chave de API

GET/v1/me

Recupera informações sobre a chave de API usada na autenticação.

Campos da resposta

apiKeyName string

Nome de exibição da chave de API.

createdAt string

Data de criação da chave de API (ISO 8601).

userId integer (chaves com escopo de usuário)

ID numérico do usuário do Cherri Code proprietário da chave de API. Omitido para chaves de API de conta de serviço / equipe, que não estão vinculadas a um usuário específico.

userEmail string (chaves com escopo de usuário)

Endereço de e-mail do proprietário da chave de API.

userFirstName, userLastName string (chaves com escopo de usuário)

Nome e sobrenome do proprietário da chave de API, quando informados.

curl --request GET \  --url https://api.cursor.com/v1/me \  -u YOUR_API_KEY:

Resposta (chave com escopo de usuário):

{  "apiKeyName": "Production API Key",  "userId": 42,  "createdAt": "2026-04-13T18:30:00.000Z",  "userEmail": "[email protected]",  "userFirstName": "Alex",  "userLastName": "Rivera"}

Resposta (chave de conta de serviço):

{  "apiKeyName": "Production Service Account",  "createdAt": "2026-04-13T18:30:00.000Z"}

Listar modelos

GET/v1/models

Retorna os modelos recomendados que você pode informar no campo model.id em Criar um agente, junto com os parâmetros e variantes aceitos por cada modelo. Os parâmetros do modelo usam o mesmo formato de model.params de TypeScript SDK ModelSelection.

Para usar o modelo padrão configurado, omita model completamente do corpo da solicitação. O Cherri Code resolve o modelo padrão do usuário, depois o modelo padrão da equipe e, por fim, um padrão do sistema.

Campos da resposta

Cada item em items descreve um modelo:

id string

Informe este valor como model.id ao criar um agente.

displayName string

Nome legível exibido na interface do Cherri Code.

description string (opcional)

Descrição curta do modelo.

aliases matriz (opcional)

IDs alternativos que apontam para o mesmo modelo (por exemplo, composer-latest).

parameters matriz (opcional)

Definições de parâmetro por modelo. Cada entrada tem um id, um displayName opcional e uma matriz values com entradas permitidas { value, displayName? }. Use isso para preencher model.params na solicitação de criação.

variants matriz (opcional)

Combinações concretas de id + params aceitas pelo modelo. Cada entrada tem uma matriz params (que pode estar vazia), um displayName, uma description opcional e um sinalizador isDefault opcional.

curl --request GET \  --url https://api.cursor.com/v1/models \  -u YOUR_API_KEY:

Resposta:

{  "items": [    {      "id": "composer-2",      "displayName": "Composer 2",      "aliases": ["composer-latest", "composer"],      "parameters": [        {          "id": "fast",          "displayName": "Fast",          "values": [            { "value": "false" },            { "value": "true", "displayName": "Fast" }          ]        }      ],      "variants": [        {          "params": [{ "id": "fast", "value": "true" }],          "displayName": "Composer 2",          "isDefault": true        },        {          "params": [{ "id": "fast", "value": "false" }],          "displayName": "Composer 2"        }      ]    },    {      "id": "claude-4.6-sonnet-thinking",      "displayName": "Claude 4.6 Sonnet (Thinking)",      "variants": [        {          "params": [],          "displayName": "Claude 4.6 Sonnet (Thinking)",          "isDefault": true        }      ]    }  ]}

Listar repositórios do GitHub

GET/v1/repositories

Lista os repositórios do GitHub acessíveis ao usuário autenticado por meio da instalação do app do GitHub do Cherri Code.

Este endpoint tem limites de taxa muito rígidos.

Limite as solicitações a 1 / usuário / minuto e 30 / usuário / hora.

Esta solicitação pode levar dezenas de segundos para retornar para usuários com acesso a muitos repositórios.

Certifique-se de tratar adequadamente os casos em que essas informações não estiverem disponíveis.

curl --request GET \  --url https://api.cursor.com/v1/repositories \  -u YOUR_API_KEY:

Resposta:

{  "items": [    {      "url": "https://github.com/your-org/your-repo"    }  ]}

API Cloud Agents

Beta público

A API Cloud Agents v1 está em beta público. As APIs podem mudar antes da disponibilidade geral.

A API Cloud Agents permite iniciar e gerenciar programaticamente agentes na nuvem que trabalham nos seus repositórios.

A API Cloud Agents aceita autenticação Basic e Bearer. Gere uma chave de API de usuário no dashboard do Cherri Code → Chaves de API ou use uma chave de API de conta de serviço.
Para mais detalhes sobre métodos de autenticação, limite de taxa e boas práticas, consulte a Visão geral da API.
Veja a especificação OpenAPI completa para ver esquemas detalhados e exemplos.
Webhooks estarão disponíveis em breve. A API v0 legada ainda oferece suporte a eles — consulte Webhooks.

Migrando da v0?

Esta API divide o trabalho em um agente persistente mais execuções por prompt, substituindo a interface mais simples da v0. A referência legada da v0 continua disponível.

O limite de 15 MB por imagem indicado abaixo se aplica às imagens enviadas pela API. Os anexos na Web em cursor.com/agents usam limites separados. Consulte Limites de anexos do Cloud Agent na Web.

Endpoints

Criar um agente

POST/v1/agents

Crie um Cloud Agent e enfileire imediatamente sua execução inicial. A resposta retorna tanto o agent durável quanto o run inicial.

Corpo da solicitação

prompt objeto (obrigatório)

O prompt da tarefa para o agente, incluindo imagens opcionais.

prompt.text string (obrigatório)

O texto de instrução para o agente.

prompt.images array (opcional)

model objeto (opcional)

model.id string (obrigatório se model for fornecido)

Um ID de modelo explícito retornado por GET /v1/models (por exemplo, claude-4-sonnet-thinking).

model.params array (opcional)

name string (opcional)

Nome exibido do agente. Máximo de 100 caracteres. Quando omitido, o Cherri Code deriva automaticamente um nome a partir do prompt.

env objeto (opcional)

env.type string (obrigatório se env for fornecido)

Tipo de ambiente de execução. cloud usa VMs hospedadas pelo Cursor; pool e machine direcionam para seus próprios workers.

env.name string (opcional)

repos matriz (opcional)

repos[0].url string (obrigatório)

URL do repositório no GitHub (por exemplo, https://github.com/your-org/your-repo). Obrigatório em toda entrada de repositório, inclusive quando prUrl for fornecido.

repos[0].startingRef string (opcional)

Nome do branch ou SHA do commit a ser usado como ponto de partida. Ignorado quando prUrl for fornecido.

repos[0].prUrl string (opcional)

URL do pull request do GitHub. Quando fornecida, o agente atua no repositório e nos branches deste PR; startingRef é ignorado. url ainda deve ser definido na mesma entrada de repos.

workOnCurrentBranch booleano (opcional, padrão: false)

autoCreatePR booleano (opcional)

Se o Cherri Code deve abrir um pull request quando a execução for concluída.

skipReviewerRequest booleano (opcional)

Se deve pular a solicitação do usuário como revisor quando o Cherri Code abrir um PR. Aplica-se apenas quando autoCreatePR for true.

envVars objeto (opcional)

mcpServers array (opcional)

mcpServers[0].name string (obrigatório)

O nome do servidor MCP exposto ao agente.

mcpServers[0].type string (opcional)

Tipo de transporte: http, sse ou stdio. Padrão: http para servidores remotos com url e stdio para servidores com command.

mcpServers[0].url string (obrigatório para MCP remoto)

URL HTTP ou HTTPS para um servidor MCP remoto. URLs com nome de usuário ou senha não são permitidas.

mcpServers[0].command string (obrigatório para MCP stdio)

Comando para iniciar um servidor MCP stdio dentro da VM do agente em nuvem. Use args e env para argumentos e segredos em tempo de execução.

customSubagents array (opcional)

mode string (opcional, padrão: agent)

Modo de conversa inicial para a primeira execução do agente. plan explora e elabora um plano antes de codificar (Modo de planejamento); agent implementa as alterações diretamente.

agentId string (opcional)

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  }'

Pool de workers (incluindo qualquer repositório):

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

Resposta:

{  "agent": {    "id": "bc-00000000-0000-0000-0000-000000000001",    "name": "Adicionar README com instruções de configuração",    "status": "ACTIVE",    "env": {      "type": "cloud"    },    "repos": [      {        "url": "https://github.com/your-org/your-repo",        "startingRef": "main"      }    ],    "workOnCurrentBranch": false,    "autoCreatePR": true,    "url": "/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"  }}

Listar agentes

GET/v1/agents

Lista os agentes do usuário autenticado, do mais recente para o mais antigo.

Parâmetros de consulta

limit number (optional)

Número de agentes a retornar. Padrão: 20, Máx.: 100.

cursor string (optional)

Cherri Code de paginação obtido de nextCursor na resposta anterior.

prUrl string (optional)

Filtra agentes pela URL do pull request do GitHub.

includeArchived boolean (optional, default: true)

Indica se a resposta deve incluir agentes arquivados.

Os itens da lista incluem apenas os campos de identidade persistente. Chame GET /v1/agents/{id} para carregar o registro completo (repos, workOnCurrentBranch, autoCreatePR, etc.).

nextCursor é omitido da resposta quando não há mais páginas — ele não é retornado como null. Trate sua ausência como "não há mais resultados".

curl --request GET \  --url 'https://api.cursor.com/v1/agents?limit=20' \  -u YOUR_API_KEY:

Resposta:

{  "items": [    {      "id": "bc-00000000-0000-0000-0000-000000000001",      "name": "Add README with setup instructions",      "status": "ACTIVE",      "env": {        "type": "cloud"      },      "url": "/agents/bc-00000000-0000-0000-0000-000000000001",      "createdAt": "2026-04-13T18:30:00.000Z",      "updatedAt": "2026-04-13T18:45:00.000Z",      "latestRunId": "run-00000000-0000-0000-0000-000000000001"    }  ],  "nextCursor": "bc-00000000-0000-0000-0000-000000000002"}

Consultar um agente

GET/v1/agents/{id}

Recupere os metadados persistentes de um agente. O status de execução está nas execuções — consulte latestRunId e chame Obter uma execução para ver o estado da execução.

Parâmetros de caminho

id string

Identificador único do agente (por exemplo, bc-00000000-0000-0000-0000-000000000001).

Campo da resposta

status string

Status do ciclo de vida do agente. Os controladores o usam para decidir se uma máquina precisa permanecer ativa:

ACTIVE — Uma interação está em execução, aguardando trabalho em segundo plano ou prestes a iniciar. Mantenha a máquina do agente ativa.
IDLE — A última interação foi concluída e mensagens de acompanhamento são aceitas. A máquina do agente pode ser hibernada ou ter um snapshot criado. Execuções que terminaram com um erro recuperável também informam IDLE; os detalhes do erro no nível da execução permanecem em Obter uma execução.
ARCHIVED — O agente foi arquivado ou expirou. Estado terminal; as claims terminam e o estado do espaço de trabalho pode ser excluído.

curl --request GET \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001 \  -u YOUR_API_KEY:

Resposta:

{  "id": "bc-00000000-0000-0000-0000-000000000001",  "name": "Adicionar README com instruções de configuração",  "status": "ACTIVE",  "env": {    "type": "cloud"  },  "repos": [    {      "url": "https://github.com/your-org/your-repo",      "startingRef": "main"    }  ],  "workOnCurrentBranch": false,  "autoCreatePR": true,  "url": "/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"}

Criar uma execução

POST/v1/agents/{id}/runs

Envie um prompt de acompanhamento para um agente ativo existente. A nova execução usa a conversa e o estado atual do espaço de trabalho do agente.

Parâmetros de caminho

id string

Identificador único do agente (por exemplo, bc-00000000-0000-0000-0000-000000000001).

Corpo da solicitação

prompt objeto (obrigatório)

O prompt de acompanhamento, incluindo imagens opcionais.

prompt.text string (obrigatório)

O texto da instrução do prompt de acompanhamento.

prompt.images matriz (opcional)

mcpServers matriz (opcional)

mode string (opcional)

Substituição do modo de conversa para esta execução de acompanhamento: agent ou plan. Omita para manter o modo atual da conversa das execuções anteriores.

curl --request POST \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/runs \  -u YOUR_API_KEY: \  --header 'Content-Type: application/json' \  --data '{    "prompt": {      "text": "Also add troubleshooting steps"    },    "mcpServers": [      {        "name": "docs",        "type": "http",        "url": "https://example.com/mcp"      }    ]  }'

Resposta:

{  "run": {    "id": "run-00000000-0000-0000-0000-000000000002",    "agentId": "bc-00000000-0000-0000-0000-000000000001",    "status": "CREATING",    "createdAt": "2026-04-13T18:50:00.000Z",    "updatedAt": "2026-04-13T18:50:00.000Z"  }}

Listar execuções

GET/v1/agents/{id}/runs

Lista as execuções de um agente, da mais recente para a mais antiga.

Parâmetros de caminho

id string

Identificador único do agente.

Parâmetros de consulta

limit number (opcional)

Número de execuções a retornar. Padrão: 20, Máx.: 100.

cursor string (opcional)

Cherri Code de paginação de nextCursor da resposta anterior.

curl --request GET \  --url 'https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/runs?limit=20' \  -u YOUR_API_KEY:

Resposta:

{  "items": [    {      "id": "run-00000000-0000-0000-0000-000000000002",      "agentId": "bc-00000000-0000-0000-0000-000000000001",      "status": "RUNNING",      "createdAt": "2026-04-13T18:50:00.000Z",      "updatedAt": "2026-04-13T18:51:00.000Z",      "git": {        "branches": [          {            "repoUrl": "github.com/your-org/your-repo",            "branch": "cursor/add-readme-a1b2"          }        ]      }    }  ]}

Obter uma execução

GET/v1/agents/{id}/runs/{runId}

Recupera o status, os timestamps e, no caso de execuções de terminal, o resultado final, a duração e os branches enviados por push de uma execução específica.

Parâmetros de caminho

id string

Identificador único do agente.

runId string

Identificador único da execução (por exemplo, run-00000000-0000-0000-0000-000000000001).

Campos da resposta

Os campos base da execução (id, agentId, status, createdAt, updatedAt) estão sempre presentes. Os campos a seguir são preenchidos assim que os dados ficam disponíveis:

durationMs integer (execuções de terminal)

Duração total da execução em milissegundos, calculada quando a execução atinge FINISHED, ERROR, CANCELLED ou EXPIRED.

result string (execuções de terminal)

Texto da resposta final do assistente para uma execução encerrada.

git object (quando um branch foi enviado por push)

repoUrl é retornado sem o esquema (por exemplo, github.com/your-org/your-repo) — diferente de repos[].url da solicitação, que mantém o prefixo https://.

curl --request GET \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/runs/run-00000000-0000-0000-0000-000000000001 \  -u YOUR_API_KEY:

Resposta:

{  "id": "run-00000000-0000-0000-0000-000000000001",  "agentId": "bc-00000000-0000-0000-0000-000000000001",  "status": "FINISHED",  "createdAt": "2026-04-13T18:30:00.000Z",  "updatedAt": "2026-04-13T18:45:00.000Z",  "durationMs": 12357,  "result": "README.md adicionado com instruções de instalação e exemplos de uso.",  "git": {    "branches": [      {        "repoUrl": "github.com/your-org/your-repo",        "branch": "cursor/add-readme-a1b2",        "prUrl": "https://github.com/your-org/your-repo/pull/123"      }    ]  }}

Stream de uma execução

GET/v1/agents/{id}/runs/{runId}/stream

Transmite eventos SSE de uma execução. O stream é limitado à execução solicitada e não reproduz execuções anteriores.

Tipos de evento

status — atualização do status da execução. Payload: { runId, status }.
assistant — delta de texto do assistente. Payload: { text }.
thinking — delta de texto de raciocínio. Payload: { text }.
tool_call — atualização do status da chamada de ferramenta. Payload: { callId, name, status, args?, result?, truncated? }.
interaction_update — evento opcional mais detalhado emitido junto com os eventos simplificados acima. O payload corresponde ao formato InteractionUpdate consumido pelo TypeScript SDK, com subtipos como text-delta, tool-call-started / tool-call-completed, step-started / step-completed e turn-ended. Se você só precisa de texto simples e chamadas de ferramenta, processe os eventos simplificados e ignore interaction_update. Se quiser o stream completo no formato do SDK, processe interaction_update e ignore os eventos simplificados.
heartbeat — evento de keepalive. Payload: {}.
result — status terminal da execução. Payload: { runId, status, text?, durationMs?, git? }. text é a resposta final do assistente, durationMs é a duração total da execução em milissegundos, e git espelha Run.git (os branches atuais enviados por push pelo agente, não apenas os desta execução).
error — erro do stream. Payload: { code, message }.
done — stream concluído. Payload: {}.

Payloads de chamada de ferramenta

Os eventos tool_call usam um envelope estável para entradas e saídas específicas da ferramenta:

type JsonValue =  | string  | number  | boolean  | null  | JsonValue[]  | { [key: string]: JsonValue };interface ToolCallEventData {  callId: string;  name: string;  status: "running" | "completed";  args?: JsonValue;  result?: JsonValue;  truncated?: {    args?: true;    result?: true;  };}

Retomando um stream

Retenção

curl --request GET \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/runs/run-00000000-0000-0000-0000-000000000001/stream \  -u YOUR_API_KEY: \  --header 'Accept: text/event-stream'

Exemplo de stream:

event: statusdata: {"runId":"run-00000000-0000-0000-0000-000000000001","status":"RUNNING"}id: 1713033000000-0event: assistantdata: {"text":"I'll update the README now."}id: 1713033005000-0event: tool_calldata: {"callId":"call-1","name":"read_file","status":"running","args":{"path":"README.md"}}id: 1713033006000-0event: tool_calldata: {"callId":"call-1","name":"read_file","status":"completed","args":{"path":"README.md"},"result":{"success":{"content":"# Project","totalLines":1,"fileSize":9,"path":"README.md"}}}id: 1713033010000-0event: resultdata: {"runId":"run-00000000-0000-0000-0000-000000000001","status":"FINISHED","text":"Added README.md with installation instructions.","durationMs":12357,"git":{"branches":[{"repoUrl":"github.com/your-org/your-repo","branch":"cursor/add-readme-a1b2"}]}}id: 1713033010000-0event: donedata: {}

Cancelar uma execução

POST/v1/agents/{id}/runs/{runId}/cancel

Cancelar uma execução que já está em estado terminal, ou que nunca esteve ativa, retorna 409 run_not_cancellable.

Parâmetros de caminho

id string

Identificador único do agente.

runId string

Identificador único da execução a ser cancelada.

curl --request POST \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/runs/run-00000000-0000-0000-0000-000000000001/cancel \  -u YOUR_API_KEY:

Resposta:

{  "id": "run-00000000-0000-0000-0000-000000000001"}

Consultar uso do agente

GET/v1/agents/{id}/usage

Parâmetros de caminho

id string

Identificador único do agente (por exemplo, bc-00000000-0000-0000-0000-000000000001).

Parâmetros de consulta

runId string (optional)

Campos da resposta

totalUsage object

Uso de tokens somado em todas as execuções retornadas. Contém os mesmos campos do objeto usage de cada execução.

runs array

Uso por execução, com uma entrada por execução (ou uma única entrada quando runId está definido). Cada objeto contém:

id string - Identificador da execução (por exemplo, run-00000000-0000-0000-0000-000000000001).
usageUuid string (optional) - Identificador interno de uso da execução. Omitido quando a execução ainda não tem uso registrado.
usage object - Uso de tokens desta execução:
- inputTokens number - Tokens de entrada consumidos.
- outputTokens number - Tokens de saída gerados.
- cacheWriteTokens number - Tokens gravados no cache.
- cacheReadTokens number - Tokens lidos do cache.
- totalTokens number - Soma das quatro contagens de tokens acima.

# Todas as execuções no agentecurl --request GET \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/usage \  -u YOUR_API_KEY:# Uma única execuçãocurl --request GET \  --url 'https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/usage?runId=run-00000000-0000-0000-0000-000000000001' \  -u YOUR_API_KEY:

Resposta:

{  "totalUsage": {    "inputTokens": 12480,    "outputTokens": 3110,    "cacheWriteTokens": 18200,    "cacheReadTokens": 42600,    "totalTokens": 76390  },  "runs": [    {      "id": "run-00000000-0000-0000-0000-000000000002",      "usageUuid": "00000000-0000-0000-0000-000000000002",      "usage": {        "inputTokens": 6320,        "outputTokens": 1450,        "cacheWriteTokens": 7100,        "cacheReadTokens": 21300,        "totalTokens": 36170      }    },    {      "id": "run-00000000-0000-0000-0000-000000000001",      "usageUuid": "00000000-0000-0000-0000-000000000001",      "usage": {        "inputTokens": 6160,        "outputTokens": 1660,        "cacheWriteTokens": 11100,        "cacheReadTokens": 21300,        "totalTokens": 40220      }    }  ]}

Artefatos

Os artefatos são vinculados ao agente porque o espaço de trabalho persiste entre execuções.

Listar artefatos

GET/v1/agents/{id}/artifacts

Lista os artefatos gerados por um agente. O path de cada artefato é relativo ao diretório artifacts/ do espaço de trabalho.

Passe o valor de path retornado aqui diretamente para Baixar um artefato. Os caminhos da v1 são relativos; caminhos absolutos da v0 (/opt/cursor/artifacts/...) não são aceitos.

Parâmetros de caminho

id string

Identificador único do agente.

curl --request GET \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/artifacts \  -u YOUR_API_KEY:

Resposta:

{  "items": [    {      "path": "artifacts/screenshot.png",      "sizeBytes": 12345,      "updatedAt": "2026-04-13T18:45:00.000Z"    }  ]}

Baixar um artefato

GET/v1/agents/{id}/artifacts/download

Retorna uma URL S3 temporária pré-assinada, válida por 15 minutos, para um artefato específico.

Parâmetros de caminho

id string

Identificador único do agente.

Parâmetros de consulta

path string

Caminho relativo do artefato retornado por Listar artefatos (por exemplo, artifacts/screenshot.png). Deve estar em artifacts/.

curl --request GET \  --url 'https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/artifacts/download?path=artifacts/screenshot.png' \  -u YOUR_API_KEY:

Resposta:

{  "url": "https://cloud-agent-artifacts.s3.us-east-1.amazonaws.com/...",  "expiresAt": "2026-04-13T19:00:00.000Z"}

Ciclo de vida do agente

Arquivar um agente

POST/v1/agents/{id}/archive

Arquive um agente. Agentes arquivados continuam legíveis, mas não podem aceitar novas execuções até serem desarquivados. Use isso em fluxos reversíveis de "exclusão suave".

Arquivar é idempotente — arquivar novamente um agente já arquivado retorna 200 sem alteração. Você não precisa verificar o estado atual antes de chamar.

Parâmetros de caminho

id string

Identificador único do agente.

curl --request POST \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/archive \  -u YOUR_API_KEY:

Resposta:

{  "id": "bc-00000000-0000-0000-0000-000000000001"}

Desarquivar um agente

POST/v1/agents/{id}/unarchive

Desarquive um agente para que ele volte a aceitar novas execuções.

Desarquivar é idempotente — chamá-lo em um agente já ativo retorna 200 sem alteração.

Parâmetros de caminho

id string

Identificador único do agente.

curl --request POST \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/unarchive \  -u YOUR_API_KEY:

Resposta:

{  "id": "bc-00000000-0000-0000-0000-000000000001"}

Excluir um agente permanentemente

DELETE/v1/agents/{id}

Exclua permanentemente um agente. Esta ação é irreversível. Use Arquivar para uma exclusão reversível.

Parâmetros de caminho

id string

Identificador único do agente.

curl --request DELETE \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001 \  -u YOUR_API_KEY:

Resposta:

{  "id": "bc-00000000-0000-0000-0000-000000000001"}

Tokens de worker

Criar um token de worker com escopo de usuário

POST/v1/sub-tokens

Crie um token com escopo de usuário com duração de uma hora para um worker ser executado como um membro ativo da equipe.

Requer uma chave de API de conta de serviço da equipe com escopo de agente. Tokens com escopo de usuário não podem gerar outros tokens com escopo de usuário.

O token retornado expira após 1 hora e não pode ser renovado automaticamente. Gere um novo token com a chave de API da conta de serviço quando precisar renovar o token de um worker em execução.

Corpo da solicitação

Especifique exatamente um dos itens a seguir para identificar o usuário de destino:

forUserEmail string (opcional)

Email do membro ativo da equipe. Não diferencia maiúsculas de minúsculas.

forUserId integer (opcional)

ID numérico de usuário do Cherri Code do membro ativo da equipe.

Por email:

curl --request POST \  --url https://api.cursor.com/v1/sub-tokens \  --header "Authorization: Bearer $CURSOR_SERVICE_ACCOUNT_API_KEY" \  --header "Content-Type: application/json" \  --data '{    "forUserEmail": "[email protected]"  }'

Por ID de usuário:

curl --request POST \  --url https://api.cursor.com/v1/sub-tokens \  --header "Authorization: Bearer $CURSOR_SERVICE_ACCOUNT_API_KEY" \  --header "Content-Type: application/json" \  --data '{    "forUserId": 42  }'

Resposta:

{  "accessToken": "eyJ...",  "expiresAt": "2026-04-24T19:00:00.000Z",  "userId": 42,  "teamId": 456}

Workers e Pools

Os caminhos de endpoint mantêm o nome antigo private-workers; eles se referem aos mesmos workers de Self-Hosted Machines.

Autentique-se com a chave de API da conta de serviço do pool via Basic auth ou Bearer token. Outros tipos de chave de API são rejeitados.

Listar workers

GET/v0/private-workers

Lista os workers do pool da equipe da conta de serviço autenticada, do mais recente ao mais antigo.

Parâmetros de consulta

status string (opcional, padrão: all)

Filtra por status do worker. Valores possíveis: all, in_use ou idle.

scope string (opcional, padrão: all)

Filtra por escopo do worker. Valores possíveis: all, team_pool ou personal.

limit integer (opcional, padrão: 50)

Resultados por página. Intervalo: de 1 a 100.

pageToken string (opcional)

Cherri Code de paginação. Informe o nextPageToken da resposta anterior.

Campos da resposta

workers array

Workers conectados. Cada item inclui:

workerId string — Identificador exclusivo do worker. IDs gerados automaticamente são UUIDs; workers iniciados com CURSOR_AGENT_WORKER_ID informam esse ID personalizado.
isInUse boolean — Indica se o worker tem um agente atribuído no momento.
repoOwner, repoName string — Metadados do repositório principal quando o worker registrou um remote do Git. Strings vazias para workers com qualquer repositório.
repoUrl string (opcional) — URL do repositório principal. Omitido para workers com qualquer repositório.
workspaceRootPath string — Caminho do espaço de trabalho principal no worker.
connectedAtMs integer — Horário da conexão em milissegundos Unix.
userId integer — ID do usuário proprietário. 0 para workers autenticados com uma chave de conta de serviço.
teamId integer (opcional) — ID da equipe para workers do pool da equipe.
serviceAccountId string (opcional) — Conta de serviço que autenticou o worker.
activeBcId string (opcional) — ID do agente em execução no worker, quando estiver em uso.
name string (opcional) — Nome de exibição do worker (--name, o valor padrão é o hostname da máquina).

totalCount integer

Total de workers que correspondem ao filtro em todas as páginas.

nextPageToken string (opcional)

Cherri Code de paginação para pageToken. Omitido quando não há mais páginas.

curl --request GET \  --url "https://api.cursor.com/v0/private-workers?status=idle&scope=team_pool&limit=50" \  -u "$CURSOR_API_KEY:"

Resposta:

{  "workers": [    {      "workerId": "a8574fe8-248e-424a-a078-7584a2b93724",      "repoOwner": "acme",      "repoName": "payments-service",      "repoUrl": "https://github.com/acme/payments-service",      "workspaceRootPath": "/home/agent/payments-service",      "connectedAtMs": 1737306880000,      "userId": 0,      "teamId": 456,      "serviceAccountId": "sa_abc123",      "isInUse": false,      "name": "gpu-worker-1"    }  ],  "totalCount": 1}

Obter resumo do worker

GET/v0/private-workers/summary

Retorna o número de workers conectados e em uso para o usuário autenticado e sua equipe. Use isso para acionar decisões de escalonamento quando a utilização estiver alta.

curl --request GET \  --url "https://api.cursor.com/v0/private-workers/summary" \  -u "$CURSOR_API_KEY:"

Exemplo de verificação de escalonamento:

const summary = await response.json();const team = summary.teamSummary;if (team && team.totalConnected > 0) {  const utilization = team.inUse / team.totalConnected;  if (utilization >= 0.9) {    // Aumentar a escala: provisionar workers adicionais  }}

Obter worker por ID

GET/v0/private-workers/{id}

Recupere um worker específico do pool pelo ID.

Parâmetros de caminho

id string

Identificador único do worker (por exemplo, pw_123).

curl --request GET \  --url "https://api.cursor.com/v0/private-workers/pw_123" \  -u "$CURSOR_API_KEY:"

Listar pools

GET/v0/private-workers/pools

Parâmetros de consulta

scope string (opcional)

Filtre pelo escopo da lista de pools. Pode ser all, team_pool ou personal.

includeStale boolean (opcional, padrão: false)

Quando true, inclui pools marcados como inativos após um longo período sem atividade.

Campos da resposta

pools matriz

Pools registrados. Cada entrada inclui:

scope string — Escopo de propriedade do pool (user ou team).
ownerId integer — ID do usuário ou da equipe proprietária no escopo.
poolName string — Nome do pool (por exemplo, default ou gpu).
connectedWorkerCount integer — Workers atualmente conectados a este pool.
inUseWorkerCount integer — Workers conectados que têm um agente atribuído no momento. A capacidade ociosa é connectedWorkerCount - inUseWorkerCount.
firstSeenAtMs, lastSeenAtMs integer — Horários da primeira e da última observação em milissegundos Unix.
isStale boolean — Indica se o pool está marcado como inativo após um longo período sem atividade.
repoOwner, repoName, repoUrl string (opcional) — Metadados do repositório quando o pool está vinculado a um repositório. Omitidos para pools de qualquer repositório.
workerReadyTimeoutSeconds integer — Segundos que uma solicitação reservada aguarda o worker desconectado deste pool se reconectar antes que a reserva expire. 0 significa que as mensagens de acompanhamento de um worker desconectado voltam a buscar um worker no pool imediatamente.

curl --request GET \  --url "https://api.cursor.com/v0/private-workers/pools?scope=team_pool&includeStale=false" \  -u "$CURSOR_API_KEY:"

Resposta:

{  "pools": [    {      "scope": "team",      "ownerId": 456,      "poolName": "gpu",      "repoOwner": "acme",      "repoName": "payments-service",      "repoUrl": "https://github.com/acme/payments-service",      "connectedWorkerCount": 2,      "inUseWorkerCount": 1,      "firstSeenAtMs": 1737000000000,      "lastSeenAtMs": 1737306880000,      "isStale": false,      "workerReadyTimeoutSeconds": 900    },    {      "scope": "team",      "ownerId": 456,      "poolName": "sandbox",      "connectedWorkerCount": 0,      "inUseWorkerCount": 0,      "firstSeenAtMs": 1737100000000,      "lastSeenAtMs": 1737200000000,      "isStale": false,      "workerReadyTimeoutSeconds": 0    }  ]}

A entrada sandbox é de qualquer repositório: os campos de repositório são omitidos, e o pool continua selecionável mesmo sem workers conectados.

Registrar um pool

POST/v0/private-workers/pools

Corpo da solicitação

scope string (obrigatório)

Escopo de propriedade do pool. Pode ser user ou team.

poolName string (obrigatório)

Nome do pool a registrar (por exemplo, gpu).

repoOwner, repoName string (opcional)

Metadados do repositório quando o pool está vinculado a um repositório. Informe ambos ou omita ambos para um pool de qualquer repositório.

repoUrl string (opcional)

URL do repositório para exibição. Requer repoOwner e repoName.

workerReadyTimeoutSeconds integer (opcional, padrão: 0)

Campos da resposta

registered boolean

Indica se o pool foi registrado.

curl --request POST \  --url "https://api.cursor.com/v0/private-workers/pools" \  -u "$CURSOR_API_KEY:" \  --header 'Content-Type: application/json' \  --data '{    "scope": "team",    "poolName": "payments-pool",    "repoOwner": "acme",    "repoName": "payments-service",    "repoUrl": "https://github.com/acme/payments-service"  }'

Resposta:

{  "registered": true}

Remover o Registro de um Pool

DELETE/v0/private-workers/pools

Parâmetros de consulta

scope string (obrigatório)

Escopo de propriedade do pool. user ou team.

pool_name string (obrigatório)

Nome do pool cujo registro será removido.

repo_owner string (opcional)

Proprietário do repositório ao remover o registro de um pool com escopo de repositório.

repo_name string (opcional)

Nome do repositório ao remover o registro de um pool com escopo de repositório. Informe repo_owner e repo_name juntos ou omita ambos para um pool de qualquer repositório.

curl --request DELETE \  --url "https://api.cursor.com/v0/private-workers/pools?scope=team&pool_name=sandbox" \  -u "$CURSOR_API_KEY:"

Resposta:

{  "deregistered": true}

Listar solicitações pendentes do pool

GET/v0/private-workers/pending-requests

A resposta inclui um streamCursor. Passe-o para Monitorar solicitações pendentes do pool para acompanhar alterações na fila em tempo real após este snapshot.

Parâmetros de consulta

limit número (opcional)

Número de solicitações pendentes a retornar. Padrão: 50, Máximo: 100.

pageToken string (opcional)

Cherri Code de paginação da resposta anterior. Os tokens de página estão vinculados aos filtros repository e pool que os emitiram.

repository string (opcional)

Filtre por URL do repositório. Obrigatório para chaves de API de conta de serviço com escopo de repositório. Omita para solicitações pendentes de qualquer repositório.

pool string (opcional)

Filtre pelo nome do pool. Correspondência exata, diferenciando maiúsculas de minúsculas, com o rótulo pool da solicitação. Omita para listar solicitações de todos os pools da equipe.

Campos de resposta

requests matriz

Solicitações pendentes. Cada entrada inclui:

id string — ID da solicitação pendente ou do agente (passe para Reivindicar ou Liberar uma reserva como id).
userId integer — ID do usuário do Cherri Code que criou a solicitação.
userEmail string (opcional) — E-mail do usuário solicitante, quando disponível. Use-o para selecionar capacidade associada ao usuário sem fazer outra consulta.
serviceAccountId string (opcional) — Conta de serviço associada à solicitação, quando presente.
repoOwner, repoName, repoUrl string (opcional) — Metadados do repositório quando a solicitação é destinada a um repositório. Omitidos para solicitações de pool de qualquer repositório.
labels matriz — Rótulos da solicitação como pares { key, value } (inclui repo= e pool= quando definidos).
createdAtMs integer — Horário de criação da solicitação em milissegundos Unix.
claimedWorkerId string (opcional) — Presente em entradas reivindicadas, mas offline: a solicitação foi reivindicada por este worker, que está offline no momento. Inicie um worker com este ID (CURSOR_AGENT_WORKER_ID) para retomar o agente na máquina dele.
wakeTimeoutMs integer (opcional) — Milissegundos restantes na janela de reconexão de uma entrada reivindicada, mas offline. Quando a janela expira, a reivindicação expira e a solicitação é anunciada novamente como uma entrada não reivindicada.

nextPageToken string (opcional)

Cherri Code de paginação. Omitido quando não há mais páginas. Para medir o tamanho da fila, pagine até o fim e conte as solicitações.

streamCursor string

curl --request GET \  --url "https://api.cursor.com/v0/private-workers/pending-requests?limit=50&repository=https%3A%2F%2Fgithub.com%2Facme%2Fpayments-service" \  -u "$CURSOR_API_KEY:"

Resposta:

{  "requests": [    {      "id": "bc-00000000-0000-0000-0000-000000000002",      "userId": 321,      "userEmail": "[email protected]",      "serviceAccountId": "sa_abc123",      "repoOwner": "acme",      "repoName": "payments-service",      "repoUrl": "https://github.com/acme/payments-service",      "labels": [        { "key": "repo", "value": "acme/payments-service" },        { "key": "pool", "value": "gpu" },        { "key": "env", "value": "production" }      ],      "createdAtMs": 1737306880000    }  ],  "nextPageToken": "eyJjcmVhdGVkQXRNcyI6MTczNzMwNjg4MDAwMH0=",  "streamCursor": "djQuZXhhbXBsZS1vcGFxdWUtY3Vyc29y"}

repoUrl omite credenciais incorporadas quando a URL original do repositório contém userinfo.

Monitorar Solicitações Pendentes do Pool

GET/v0/private-workers/pending-requests/stream

Receba eventos do ciclo de vida de solicitações pendentes via eventos enviados pelo servidor (SSE), para que os controladores possam reagir a alterações na fila sem fazer polling.

Parâmetros de consulta

cursor string (obrigatório)

repository string (opcional)

pool string (opcional)

Eventos

created evento — Uma solicitação entrou na fila, incluindo uma solicitação assumida, mas offline, cuja janela de reconexão se encerrou e cuja atribuição expirou. Payload: o mesmo objeto de solicitação de Listar Solicitações Pendentes do Pool.
claimed evento — Um worker assumiu a solicitação ou um worker off-line se reconectou e retomou a solicitação que havia assumido. Payload: { id }.
claimed_offline evento — Uma mensagem de acompanhamento chegou para uma solicitação cujo worker atribuído está offline. Payload: o mesmo objeto de solicitação de Listar Solicitações Pendentes do Pool, incluindo claimedWorkerId e wakeTimeoutMs. Reative a máquina antes que a janela expire, ou a atribuição expira e a solicitação é anunciada novamente com um novo evento created.
expired evento — A solicitação saiu da fila sem ser assumida. Payload: { id }.
heartbeat evento — Checkpoint do cursor sem alteração de estado, enviado aproximadamente a cada 20 segundos em um stream sem atividade. Payload: {}. Os heartbeats avançam a posição de retomada de um monitoramento inativo, mas não estendem a validade do cursor.

Tempo de vida do cursor

Garantias de entrega

Não persista cursores. Uma conta de serviço pode manter no máximo quatro streams simultâneos; use um stream por controlador e distribua os eventos localmente.

curl --request GET --no-buffer \  --url "https://api.cursor.com/v0/private-workers/pending-requests/stream?cursor=$STREAM_CURSOR" \  --header 'Accept: text/event-stream' \  -u "$CURSOR_API_KEY:"

Exemplo de stream:

: connected

event: heartbeat
id: djQuY3Vyc29yLWNoZWNrcG9pbnQ
data: {}

event: created
id: djQuY3Vyc29yLWFmdGVyLWNyZWF0ZWQ
data: {"id":"bc-00000000-0000-0000-0000-000000000002","userId":321,"userEmail":"[email protected]","repoOwner":"acme","repoName":"payments-service","repoUrl":"https://github.com/acme/payments-service","labels":[{"key":"pool","value":"gpu"}],"createdAtMs":1737306880000}

event: claimed
id: djQuY3Vyc29yLWFmdGVyLWNsYWltZWQ
data: {"id":"bc-00000000-0000-0000-0000-000000000002"}

O loop do controlador:

Liste as solicitações pendentes até a conclusão e substitua sua visualização local pelo resultado. Mantenha o streamCursor da resposta.
Abra o monitoramento com ?cursor=<streamCursor> e aplique os eventos à sua visualização local. Rastreie o id: do evento mais recente que você processou.
Em caso de desconexão, reconecte-se usando o id do evento mais recente como ?cursor=, ou use um EventSource nativo, que o reenvia automaticamente como Last-Event-ID.
Ao receber HTTP 410 Gone, volte à etapa 1 e liste novamente.

Reservar uma solicitação pendente

POST/v0/private-workers/claim

Uma segunda reserva enquanto houver uma reserva ativa é rejeitada. Libere uma reserva primeiro e, depois, reserve um novo workerId.

Este endpoint requer uma chave de API de conta de serviço.

Corpo da solicitação

id string (obrigatório)

ID da solicitação pendente. Mesmo valor de id em Listar solicitações pendentes do pool.

workerId string (obrigatório)

ID do worker a ser reservado para a solicitação. Inicie o worker com o mesmo ID usando CURSOR_AGENT_WORKER_ID (ou a flag oculta --worker-id) para que a ponte registre a identidade reservada.

sessionToken boolean (opcional, padrão: false)

Campos de resposta

id, workerId string

A solicitação reservada e o ID do worker.

token string (opcional)

expiresAt string (opcional)

Timestamp ISO 8601, 7 dias após a emissão. Presente junto com token.

curl --request POST \  --url "https://api.cursor.com/v0/private-workers/claim" \  -u "$CURSOR_API_KEY:" \  --header 'Content-Type: application/json' \  --data '{    "id": "bc-00000000-0000-0000-0000-000000000002",    "workerId": "pw_123"  }'

Resposta:

{  "id": "bc-00000000-0000-0000-0000-000000000002",  "workerId": "pw_123"}

Após reservar a solicitação, inicie o worker com o ID reservado:

export CURSOR_API_KEY="your-service-account-api-key"export CURSOR_AGENT_WORKER_ID="pw_123"agent worker --pool gpu --worker-dir /workspace start

Com um token de sessão:

curl --request POST \  --url "https://api.cursor.com/v0/private-workers/claim" \  -u "$CURSOR_API_KEY:" \  --header 'Content-Type: application/json' \  --data '{    "id": "bc-00000000-0000-0000-0000-000000000002",    "workerId": "pw_123",    "sessionToken": true  }'

Resposta:

{  "id": "bc-00000000-0000-0000-0000-000000000002",  "workerId": "pw_123",  "token": "eyJ...",  "expiresAt": "2026-10-02T21:00:00.000Z"}

Inicie o worker com o token em vez da chave:

printf '%s' "$TOKEN" > /run/cursor/tokenexport CURSOR_AGENT_WORKER_ID="pw_123"agent worker --pool gpu --worker-dir /workspace --auth-token-file /run/cursor/token start

Criar um token de sessão

POST/v0/private-workers/tokens

O token vale apenas para esta declaração. Ele deixa de funcionar quando a declaração é liberada ou quando a chave de API que o emitiu é excluída ou expira.

Corpo da solicitação

id string (obrigatório)

ID do agente ao qual a declaração se refere. Mesmo valor de id em Reservar uma solicitação pendente.

workerId string (obrigatório)

ID do worker que a declaração vincula ao agente.

curl --request POST \  --url "https://api.cursor.com/v0/private-workers/tokens" \  -u "$CURSOR_API_KEY:" \  --header 'Content-Type: application/json' \  --data '{    "id": "bc-00000000-0000-0000-0000-000000000002",    "workerId": "pw_123"  }'

Resposta:

{  "id": "bc-00000000-0000-0000-0000-000000000002",  "workerId": "pw_123",  "token": "eyJ...",  "expiresAt": "2026-10-02T21:00:00.000Z"}

HTTP 404 significa que sua equipe não detém nenhuma declaração que vincule esse worker a esse agente.

Liberar uma reserva

POST/v0/private-workers/claims/{id}/release

Remove a reivindicação de longo prazo que vincula um agente a um worker self-hosted. Após a liberação, o Cherri Code deixa de priorizar essa máquina para o agente.

Uma segunda Reservar uma solicitação pendente enquanto houver uma reivindicação ativa será rejeitada. Libere-a primeiro e, em seguida, reivindique um novo workerId.

--idle-release-timeout (var. de ambiente CURSOR_WORKER_IDLE_RELEASE_TIMEOUT) faz a CLI do worker encerrar após ficar ociosa. Este endpoint apenas remove a reivindicação de roteamento.

Este endpoint requer uma chave de API de conta de serviço.

Parâmetros de caminho

id string

ID da solicitação pendente / agente. Mesmo valor de id em Reservar uma solicitação pendente. Sem corpo da solicitação.

curl --request POST \  --url "https://api.cursor.com/v0/private-workers/claims/bc-00000000-0000-0000-0000-000000000002/release" \  -u "$CURSOR_API_KEY:"

Resposta:

{  "id": "bc-00000000-0000-0000-0000-000000000002",  "workerId": "pw_123"}

HTTP 404 significa que não há uma reivindicação ativa: ela já foi liberada, expirou ou foi adotada. Não tente novamente após um 404.

Endpoints de metadados

Informações da chave de API

GET/v1/me

Recupera informações sobre a chave de API usada na autenticação.

Campos da resposta

apiKeyName string

Nome de exibição da chave de API.

createdAt string

Data de criação da chave de API (ISO 8601).

userId integer (chaves com escopo de usuário)

ID numérico do usuário do Cherri Code proprietário da chave de API. Omitido para chaves de API de conta de serviço / equipe, que não estão vinculadas a um usuário específico.

userEmail string (chaves com escopo de usuário)

Endereço de e-mail do proprietário da chave de API.

userFirstName, userLastName string (chaves com escopo de usuário)

Nome e sobrenome do proprietário da chave de API, quando informados.

curl --request GET \  --url https://api.cursor.com/v1/me \  -u YOUR_API_KEY:

Resposta (chave com escopo de usuário):

{  "apiKeyName": "Production API Key",  "userId": 42,  "createdAt": "2026-04-13T18:30:00.000Z",  "userEmail": "[email protected]",  "userFirstName": "Alex",  "userLastName": "Rivera"}

Resposta (chave de conta de serviço):

{  "apiKeyName": "Production Service Account",  "createdAt": "2026-04-13T18:30:00.000Z"}

Listar modelos

GET/v1/models

Campos da resposta

Cada item em items descreve um modelo:

id string

Informe este valor como model.id ao criar um agente.

displayName string

Nome legível exibido na interface do Cherri Code.

description string (opcional)

Descrição curta do modelo.

aliases matriz (opcional)

IDs alternativos que apontam para o mesmo modelo (por exemplo, composer-latest).

parameters matriz (opcional)

variants matriz (opcional)

curl --request GET \  --url https://api.cursor.com/v1/models \  -u YOUR_API_KEY:

Resposta:

{  "items": [    {      "id": "composer-2",      "displayName": "Composer 2",      "aliases": ["composer-latest", "composer"],      "parameters": [        {          "id": "fast",          "displayName": "Fast",          "values": [            { "value": "false" },            { "value": "true", "displayName": "Fast" }          ]        }      ],      "variants": [        {          "params": [{ "id": "fast", "value": "true" }],          "displayName": "Composer 2",          "isDefault": true        },        {          "params": [{ "id": "fast", "value": "false" }],          "displayName": "Composer 2"        }      ]    },    {      "id": "claude-4.6-sonnet-thinking",      "displayName": "Claude 4.6 Sonnet (Thinking)",      "variants": [        {          "params": [],          "displayName": "Claude 4.6 Sonnet (Thinking)",          "isDefault": true        }      ]    }  ]}

Listar repositórios do GitHub

GET/v1/repositories

Lista os repositórios do GitHub acessíveis ao usuário autenticado por meio da instalação do app do GitHub do Cherri Code.

Este endpoint tem limites de taxa muito rígidos.

Limite as solicitações a 1 / usuário / minuto e 30 / usuário / hora.

Esta solicitação pode levar dezenas de segundos para retornar para usuários com acesso a muitos repositórios.

Certifique-se de tratar adequadamente os casos em que essas informações não estiverem disponíveis.

curl --request GET \  --url https://api.cursor.com/v1/repositories \  -u YOUR_API_KEY:

Resposta:

{  "items": [    {      "url": "https://github.com/your-org/your-repo"    }  ]}

Command Palette

Visão geral da API

API de agentes na nuvem

API de administração

API de Análise

API de rastreamento de código com IA

API de Migração de Origem

API de origem

API Cloud Agents

Command Palette

Visão geral da API

API de agentes na nuvem

API de administração

API de Análise

API de rastreamento de código com IA

API de Migração de Origem

API de origem

API Cloud Agents