Skip to main content

Command Palette

Search for a command to run...

API

Cloud Agents API

Cloud Agents API позволяет программно запускать облачных Agent-ов и управлять ими, чтобы они работали с вашими репозиториями.

Конечные точки

Создать агента

POST/v1/agents

Создаёт Cloud Agent и немедленно ставит в очередь его первоначальный запуск. В ответе возвращаются как постоянный agent, так и первоначальный run.

Тело запроса

prompt object (обязательно)

Промпт задачи для агента, включая необязательные изображения.

prompt.text строка (обязательно)

Текст инструкции для агента.

prompt.images массив (необязательно)

Входные изображения для подсказки. Каждый элемент должен содержать либо data (байты, закодированные в base64, с обязательным полем mimeType), либо url (HTTP или HTTPS URL, который Cursor получает). Максимум 5 изображений, по 15 МБ каждое. Поддерживаемые MIME-типы: image/png, image/jpeg, image/gif, image/webp.

model объект (необязательно)

Выбор модели. Оставьте это поле пустым, чтобы использовать настроенное значение по умолчанию. Если поле опущено, Cursor сначала использует модель по умолчанию пользователя, затем модель по умолчанию команды, затем системное значение по умолчанию.

model.id строка (обязательно, если указан model)

Явный идентификатор модели, возвращаемый запросом GET /v1/models (например, claude-4-sonnet-thinking).

model.params массив (необязательно)

Параметры для каждой модели, применяемые при запуске, например степень рассуждений или размер контекстного окна. Каждый элемент имеет id и value. Используйте только параметры, поддерживаемые выбранной моделью — вызовите GET /v1/models, чтобы узнать допустимые комбинации id/params.

name строка (необязательно)

Отображаемое имя агента. Не более 100 символов. Если не указано, Cursor автоматически выводит имя из подсказки.

env объект (необязательно)

Целевая среда выполнения. Используйте именованную среду cloud или направляйте выполнение в pool или machine, размещённые вами. Взаимоисключается с явным указанием repos при выборе именованной среды, размещаемой Cursor.

env.type строка (обязательно, если указан env)

Тип среды выполнения. cloud использует ВМ, размещённые Cursor; pool и machine перенаправляют на ваши собственные воркеры.

env.name строка (необязательно)

Имя среды, размещённой Cursor, пула или машины. Для env.type: "pool" это имя пула (если не указано, используется default). При неизвестном имени пула возвращается 400, вместо того чтобы бесконечно ждать в очереди.

repos массив (необязательно)

Конфигурация репозитория. Взаимно исключает указание именованной облачной среды. Не указывайте ни repos, ни env, чтобы запустить агента без репозиториев. Также можно не указывать repos, когда env.type равен pool, чтобы направить выполнение в пул с любым репозиторием. Максимум 20 репозиториев.

repos[0].url строка (обязательно)

URL репозитория GitHub (например, https://github.com/your-org/your-repo). Обязательно для каждой записи репозитория, даже если указан prUrl.

repos[0].startingRef string (необязательно)

Имя ветки или SHA коммита, используемое в качестве начальной точки. Игнорируется, если указан prUrl.

repos[0].prUrl string (необязательно)

URL pull request на GitHub. При указании агент работает с репозиторием и ветками этого PR; startingRef игнорируется. url по-прежнему должен быть задан в той же записи repos.

workOnCurrentBranch логическое (необязательно, по умолчанию: false)

При значении false (по умолчанию) Cursor отправляет коммиты в новую автоматически созданную ветку (cursor/...) на основе repos[0].startingRef (или базовой ветки PR, если задан prUrl). При значении true Cursor отправляет изменения напрямую в эту начальную ссылку — при создании без PR это ветка, переданная в startingRef; при создании с prUrl — головная ветка PR. Ветка, в которую агент отправил изменения, отображается в git.branches[] агента.

autoCreatePR логическое значение (необязательно)

Должен ли Cursor открыть pull request после завершения выполнения.

skipReviewerRequest логический (необязательно)

Пропускать ли запрос пользователя в качестве ревьюера при открытии PR Cursor. Применяется только когда autoCreatePR равно true.

envVars объект (необязательно)

Переменные среды, действующие в рамках сессии, для облачного агента. Значения шифруются в состоянии покоя, внедряются в оболочку агента и удаляются вместе с агентом. Максимум 50 записей; имена — до 255 байт (не могут начинаться с CURSOR_), значения — до 4096 байт. Нельзя сочетать с agentId, предоставленным клиентом.
Бета: envVars разворачивается постепенно. Если он ещё не включён для вашего аккаунта, это поле при создании молча игнорируется, а не приводит к ошибке запроса — перед тем как полагаться на них в продакшене, убедитесь, что значения присутствуют, проверив оболочку агента при первом запуске.

mcpServers массив (необязательно)

Встроенные определения серверов MCP, доступные агенту. Максимум 50 серверов. Удалённые серверы поддерживают headers или OAuth auth; stdio-серверы запускаются внутри облачной виртуальной машины и могут получать env. Имена серверов должны быть уникальными.

mcpServers[0].name строка (обязательно)

Имя сервера MCP, доступное агенту.

mcpServers[0].type строка (необязательно)

Тип транспорта: http, sse или stdio. По умолчанию http для удалённых серверов с url и stdio для серверов с command.

mcpServers[0].url string (обязательно для удалённого MCP)

HTTP или HTTPS URL для удалённого сервера MCP. URL-адреса с именем пользователя или паролем не допускаются.

mcpServers[0].command string (обязательно для stdio MCP)

Команда для запуска stdio MCP-сервера внутри виртуальной машины облачного агента. Используйте args и env для аргументов и секретов времени выполнения.

customSubagents массив (необязательно)

Определите пользовательских субагентов, которым основной агент может делегировать задачи во время выполнения. Максимум 20 субагентов. Каждая запись должна содержать name, description и prompt, а также необязательное поле model (строка с идентификатором модели, объект ModelSelection или "inherit"). Имена должны быть уникальными и не пересекаться с встроенными (explore, debug, shell, computerUse и т.д.).

mode string (необязательно, по умолчанию: agent)

Начальный режим диалога для первого запуска агента. plan изучает и составляет план перед написанием кода (Режим планирования); agent внедряет изменения напрямую.

agentId string (необязательно)

Идентификатор агента, предоставляемый клиентом, в формате bc-<uuid>. Полезен для идемпотентных операций создания — повторный POST с тем же agentId вернёт 409 agent_id_conflict вместо создания дубликата. Нельзя сочетать с envVars; опустите agentId, чтобы сервер выпустил его, когда понадобятся секреты сессии.
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  }'

Пул воркеров (включая любой репозиторий):

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

Ответ:

{  "agent": {    "id": "bc-00000000-0000-0000-0000-000000000001",    "name": "Add README with setup instructions",    "status": "ACTIVE",    "env": {      "type": "cloud"    },    "repos": [      {        "url": "https://github.com/your-org/your-repo",        "startingRef": "main"      }    ],    "workOnCurrentBranch": false,    "autoCreatePR": true,    "url": "https://cursor.com/agents/bc-00000000-0000-0000-0000-000000000001",    "createdAt": "2026-04-13T18:30:00.000Z",    "updatedAt": "2026-04-13T18:30:00.000Z",    "latestRunId": "run-00000000-0000-0000-0000-000000000001"  },  "run": {    "id": "run-00000000-0000-0000-0000-000000000001",    "agentId": "bc-00000000-0000-0000-0000-000000000001",    "status": "CREATING",    "createdAt": "2026-04-13T18:30:00.000Z",    "updatedAt": "2026-04-13T18:30:00.000Z"  }}

Список Agent-ов

GET/v1/agents

Возвращает список Agent-ов аутентифицированного пользователя, начиная с самых новых.

Параметры запроса

limit number (optional)

Количество возвращаемых Agent-ов. По умолчанию: 20, максимум: 100.

cursor string (optional)

Курсор пагинации из nextCursor в предыдущем ответе.

prUrl string (optional)

Фильтрует Agent-ов по URL GitHub pull request.

includeArchived boolean (optional, default: true)

Указывает, включать ли архивных Agent-ов в ответ.
curl --request GET \  --url 'https://api.cursor.com/v1/agents?limit=20' \  -u YOUR_API_KEY:

Ответ:

{  "items": [    {      "id": "bc-00000000-0000-0000-0000-000000000001",      "name": "Add README with setup instructions",      "status": "ACTIVE",      "env": {        "type": "cloud"      },      "url": "https://cursor.com/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"}

Получить Agent

GET/v1/agents/{id}

Возвращает постоянные метаданные Agent. Статус выполнения хранится в запусках: получите latestRunId и вызовите Получение запуска, чтобы узнать состояние запуска.

Параметры пути

id string

Уникальный идентификатор Agent (например, bc-00000000-0000-0000-0000-000000000001).

Поля ответа

status string

Статус жизненного цикла Agent. Контроллеры используют его, чтобы определить, должна ли машина оставаться включённой:
  • ACTIVE — Шаг выполняется, ожидает фоновой работы или вот-вот начнётся. Не выключайте машину Agent.
  • IDLE — Последний шаг завершён, и Agent доступен для последующих запросов. Машину Agent можно перевести в спящий режим или создать её снимок. Запуски, завершившиеся с устранимой ошибкой, также имеют статус IDLE; подробные сведения об ошибке для запуска доступны в Получении запуска.
  • ARCHIVED — Agent архивирован или срок его действия истёк. Окончательный статус: клеймы прекращают действовать, а состояние рабочей области можно удалить.
curl --request GET \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001 \  -u YOUR_API_KEY:

Ответ:

{  "id": "bc-00000000-0000-0000-0000-000000000001",  "name": "Add README with setup instructions",  "status": "ACTIVE",  "env": {    "type": "cloud"  },  "repos": [    {      "url": "https://github.com/your-org/your-repo",      "startingRef": "main"    }  ],  "workOnCurrentBranch": false,  "autoCreatePR": true,  "url": "https://cursor.com/agents/bc-00000000-0000-0000-0000-000000000001",  "createdAt": "2026-04-13T18:30:00.000Z",  "updatedAt": "2026-04-13T18:30:00.000Z",  "latestRunId": "run-00000000-0000-0000-0000-000000000001"}

Создать запуск

POST/v1/agents/{id}/runs

Отправьте дополнительный промпт существующему активному Agent. Новый запуск использует тек��щее состояние диалога и рабочей области Agent.

Параметры пути

id string

Уникальный идентификатор Agent (например, bc-00000000-0000-0000-0000-000000000001).

Тело запроса

prompt object (обязательно)

Дополнительный промпт, при необходимости — с изображениями.

prompt.text string (обязательно)

Текст дополнительной инструкции.

prompt.images array (необязательно)

Входные изображения для дополнительного промпта. Каждая запись должна включать либо data (байты в кодировке base64 с обязательным mimeType), либо url. Не более 5 изображений, до 15 МБ каждое. Поддерживаемые MIME-типы: image/png, image/jpeg, image/gif, image/webp.

mcpServers array (необязательно)

Определения Inline MCP‑сервер для этого запуска. Если они указаны, они заменяют все inline MCP‑серверы, заданные при создании, для этого запуска. Не указывайте это поле, чтобы сохранить текущую конфигурацию MCP Agent.

mode string (необязательно)

Переопределение режима диалога для этого запуска: agent или plan. Не указывайте это поле, чтобы сохранить текущий режим диалога из предыдущих запусков.
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": "Также добавьте шаги по устранению неполадок"    },    "mcpServers": [      {        "name": "docs",        "type": "http",        "url": "https://example.com/mcp"      }    ]  }'

Ответ:

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

Список запусков

GET/v1/agents/{id}/runs

Список запусков Agent-а, начиная с самых новых.

Параметры пути

id string

Уникальный идентификатор Agent-а.

Параметры запроса

limit number (optional)

Количество возвращаемых запусков. По умолчанию: 20, максимум: 100.

cursor string (optional)

Курсор пагинации из nextCursor в предыдущем ответе.
curl --request GET \  --url 'https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/runs?limit=20' \  -u YOUR_API_KEY:

Ответ:

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

Получение запуска

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

Возвращает статус, временные метки и (для запусков в терминальном состоянии) итоговый результат, длительность и отправленные ветки для конкретного запуска.

Параметры пути

id string

Уникальный идентификатор Agent-а.

runId string

Уникальный идентификатор запуска (например, run-00000000-0000-0000-0000-000000000001).

Поля ответа

Базовые поля запуска (id, agentId, status, createdAt, updatedAt) присутствуют всегда. Следующие поля заполняются, как только становятся доступны данные:

durationMs integer (terminal runs)

Фактическая длительность запуска в миллисекундах, вычисляемая после того, как запуск переходит в состояние FINISHED, ERROR, CANCELLED или EXPIRED.

result string (terminal runs)

Текст итогового ответа ассистента для завершённого запуска.

git object (когда ветка уже отправлена)

Текущие отправленные ветки и pull request Agent-а. git.branches[] содержит записи { repoUrl, branch?, prUrl? } — по одной для каждой ветки, которую Agent отправил (многоуровневые Agent-ы создают несколько).
Состояние на уровне Agent-а, а не запуска. Каждый запуск одного и того же Agent-а возвращает один и тот же снимок git. Используйте latestRunId Agent-а или SSE-поток, чтобы связать результаты работы с конкретным запуском.
repoUrl возвращается без схемы (например, github.com/your-org/your-repo) — в отличие от repos[].url в запросе, где сохраняется префикс 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:

Ответ:

{  "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": "Added README.md with installation instructions and usage examples.",  "git": {    "branches": [      {        "repoUrl": "github.com/your-org/your-repo",        "branch": "cursor/add-readme-a1b2",        "prUrl": "https://github.com/your-org/your-repo/pull/123"      }    ]  }}

Поток событий запуска

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

Возвращает поток Server-Sent Events (SSE) для одного запуска. Поток относится только к запрошенному запуску и не воспроизводит события предыдущих запусков.

Типы событий

  • status — обновление статуса запуска. Полезная нагрузка: { runId, status }.
  • assistant — частичное обновление текста assistant. Полезная нагрузка: { text }.
  • thinking — частичное обновление текста thinking. Полезная нагрузка: { text }.
  • tool_call — обновление статуса вызова инструмента. Полезная нагрузка: { callId, name, status, args?, result?, truncated? }.
  • interaction_update — необязательное более подробное событие, выдаваемое вместе с упрощенными событиями выше. Полезная нагрузка соответствует форме InteractionUpdate, используемой в TypeScript SDK, с такими подтипами, как text-delta, tool-call-started / tool-call-completed, step-started / step-completed и turn-ended. Если вам нужны только обычный текст и вызовы инструмента, обрабатывайте упрощенные события и игнорируйте interaction_update. Если вам нужен поток в полной форме SDK, обрабатывайте interaction_update и игнорируйте упрощенные события.
  • heartbeat — событие поддержания соединения. Полезная нагрузка: {}.
  • result — конечный статус запуска. Полезная нагрузка: { runId, status, text?, durationMs?, git? }. text — финальный ответ assistant, durationMs — длительность запуска по реальному времени в миллисекундах, а git повторяет Run.git (текущие отправленные ветки agent, а не только ветки этого запуска).
  • error — ошибка потока. Полезная нагрузка: { code, message }.
  • done — поток завершен. Полезная нагрузка: {}.

Полезная нагрузка вызовов инструмента

События tool_call используют стабильную оболочку для входных и выходных данных конкретного инструмента:

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 идентифицирует один вызов инструмента во всех обновлениях. name — публичное имя инструмента, например read_file, run_terminal_cmd или mcp. args и result — специфичные для инструмента значения JSON. Если args или result слишком велики для включения в поток, Cursor опускает это поле и задает соответствующий флаг truncated.

Возобновление потока

Большинство событий включают строку id — непрозрачную строку, которую не следует разбирать (текущий формат выглядит как 1713033006000-0, но считайте его непрозрачным). У начального события status нет id — это закрепленное служебное событие, которое повторно отправляется в начале каждого переподключения.

Чтобы возобновить поток после разрыва соединения, переподключитесь, передав в Last-Event-ID id последнего полученного события. id события должен принадлежать запрошенному запуску; в противном случае запрос вернет 400 invalid_last_event_id. После успешного возобновления ожидайте еще одно событие status перед началом возобновленного диапазона.

Срок хранения

Ответы потока включают заголовок X-Cursor-Stream-Retention-Seconds. После истечения периода хранения эта конечная точка может вернуть 410 stream_expired. Считайте это сигналом получить конечное состояние через Получение запуска, а не повторять попытку подключения к потоку.

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'

Пример потока:

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

Отменить запуск

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

Отменяет активный запуск агента. Отмена необратима — запуск переходит в состояние CANCELLED и не может быть возобновлён. Чтобы продолжить диалог, создайте новый запуск для того же агента.

Параметры пути

id string

Уникальный идентификатор агента.

runId string

Уникальный идентификатор запуска, который нужно отменить.
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:

Ответ:

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

Получение данных об использовании Agent

GET/v1/agents/{id}/usage

Возвращает использование токенов для Agent с разбивкой по каждому запуску. В ответе суммируется использование по всем запускам этого Agent, а также приводится использование для каждого отдельного запуска. Использование токенов соответствует структуре tokenUsage в эндпоинте команды usage events.

Параметры пути

id string

Уникальный идентификатор Agent (например, bc-00000000-0000-0000-0000-000000000001).

Параметры запроса

runId string (optional)

Ограничивает ответ одним запуском (например, run-00000000-0000-0000-0000-000000000001). Не указывайте этот параметр, чтобы вернуть использование для всех запусков этого Agent. Неизвестный runId возвращает 404 run_not_found.

Поля ответа

totalUsage object

Использование токенов, суммированное по всем возвращённым запускам. Содержит те же поля, что и object usage каждого запуска.

runs array

Использование по запускам: по одной записи на каждый запуск (или одна запись, если задан runId). Каждый object содержит:
  • id string - Идентификатор запуска (например, run-00000000-0000-0000-0000-000000000001).
  • usageUuid string (optional) - Внутренний идентификатор использования для запуска. Отсутствует, если для запуска ещё не зафиксировано использование.
  • usage object - Использование токенов для этого запуска:
    • inputTokens number - Количество использованных входных токенов.
    • outputTokens number - Количество сгенерированных выходных токенов.
    • cacheWriteTokens number - Количество токенов, записанных в кэш.
    • cacheReadTokens number - Количество токенов, прочитанных из кэша.
    • totalTokens number - Сумма четырёх указанных выше значений.
# Все запуски агентаcurl --request GET \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/usage \  -u YOUR_API_KEY:# Один запускcurl --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:

Ответ:

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

Артефакты

Артефакты привязаны к агенту, поскольку рабочая область сохраняется между запусками.

Список артефактов

GET/v1/agents/{id}/artifacts

Возвращает артефакты, созданные агентом. path каждого артефакта задаётся относительно каталога artifacts/ в рабочей области.

Параметры пути

id string

Уникальный идентификатор агента.
curl --request GET \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/artifacts \  -u YOUR_API_KEY:

Ответ:

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

Скачать артефакт

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

Возвращает временный presigned URL S3 для конкретного артефакта, действительный 15 минут.

Параметры пути

id string

Уникальный идентификатор агента.

Параметры запроса

path string

Относительный путь к артефакту, возвращённый в Список артефактов (например, artifacts/screenshot.png). Должен находиться в 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:

Ответ:

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

Жизненный цикл агента

Архивировать агента

POST/v1/agents/{id}/archive

Архивировать агента. Архивированные агенты остаются доступными для чтения, но не могут принимать новые запуски, пока не будут восстановлены из архива. Используйте это для обратимого «мягкого удаления».

Параметры пути

id string

Уникальный идентификатор агента.
curl --request POST \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/archive \  -u YOUR_API_KEY:

Ответ:

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

Восстановить агента из архива

POST/v1/agents/{id}/unarchive

Восстановить агента из архива, чтобы он снова мог принимать новые запуски.

Параметры пути

id string

Уникальный идентификатор агента.
curl --request POST \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/unarchive \  -u YOUR_API_KEY:

Ответ:

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

Удалить агента навсегда

DELETE/v1/agents/{id}

Удалить агента навсегда. Это действие необратимо. Для обратимого удаления используйте архивацию.

Параметры пути

id string

Уникальный идентификатор агента.
curl --request DELETE \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001 \  -u YOUR_API_KEY:

Ответ:

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

Токены воркера

Создать токен пользователя для воркера

POST/v1/sub-tokens

Создаёт токен пользователя сроком на один час для воркера, чтобы он работал от имени активного участника команды.

Требуется API-ключ сервисного аккаунта команды, привязанный к агенту. Токены пользователя не могут создавать другие токены пользователя.

Тело запроса

Укажите ровно одно из следующих значений, чтобы определить нужного пользователя:

forUserEmail string (optional)

Email активного участника команды. Регистр не учитывается.

forUserId integer (optional)

Числовой user ID активного участника команды в Cursor.

По 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": "alice@company.com"  }'

По user ID:

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

Ответ:

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

Воркеры и пулы

Отслеживайте загрузку воркеров и настраивайте автомасштабирование для своих пулов. Постоянные пулы остаются зарегистрированными после отключения последнего воркера, поэтому вы можете сократить число воркеров до нуля и снова наращивать ресурсы при появлении ожидающих запросов.

В путях конечных точек по-прежнему используется прежнее имя private-workers; они указывают на тех же воркеров.

Для аутентификации используйте API-ключ сервисного аккаунта пула через базовую аутентификацию или Bearer-токен. API-ключи других типов отклоняются.

Список воркеров

GET/v0/private-workers

Список воркеров из пула для команды аутентифицированного сервисного аккаунта, начиная с самых новых.

Параметры запроса

status строка (необязательный, по умолчанию: all)

Фильтрация по статусу воркера. Один из вариантов: all, in_use или idle.

scope строка (необязательный, по умолчанию: all)

Фильтрация по области действия воркера. Один из вариантов: all, team_pool или personal.

limit целое число (не��бязательный, по умолчанию: 50)

Количество результатов на странице. Диапазон: от 1 до 100.

pageToken строка (необязательный)

Курсор пагинации. Передайте nextPageToken из предыдущего ответа.

Поля ответа

workers массив

Подключённые воркеры. Каждая запись содержит:
  • workerId строка — Уникальный идентификатор воркера. Автоматически сгенерированные ID — это UUID; воркеры, запущенные с CURSOR_AGENT_WORKER_ID, вместо этого сообщают этот пользовательский ID.
  • isInUse логическое значение — Назначен ли воркеру Agent.
  • repoOwner, repoName строка — Основные метаданные репозитория, если воркер зарегистрировал удалённый репозиторий Git. Для воркеров, работающих с любым репозиторием, — пустые строки.
  • repoUrl строка (необязательная) — Основной URL-адрес репозитория. Не указывается для воркеров, работающих с любым репозиторием.
  • workspaceRootPath строка — Основной путь к рабочему пространству на воркере.
  • connectedAtMs целое число — Время подключения в миллисекундах Unix.
  • userId целое число — ID пользователя-владельца. 0 для воркеров, аутентифицированных с помощью ключа сервисного аккаунта.
  • teamId целое число (необязательный) — ID команды для воркеров командного пула.
  • serviceAccountId строка (необязательный) — Сервисный аккаунт, аутентифицировавший воркер.
  • activeBcId строка (необязательный) — ID Agent, который сейчас выполняется на воркере, если он используется.
  • name строка (необязательный) — Отображаемое имя воркера (--name, по умолчанию — имя хоста машины).

totalCount целое число

Общее количество воркеров, соответствующих фильтру, на всех страницах.

nextPageToken строка (необязательный)

Курсор пагинации для pageToken. Не указывается, если других страниц нет.
curl --request GET \  --url "https://api.cursor.com/v0/private-workers?status=idle&scope=team_pool&limit=50" \  -u "$CURSOR_API_KEY:"

Ответ:

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

Получить сводку по воркерам

GET/v0/private-workers/summary

Возвращает количество подключенных и занятых воркеров для аутентифицированного пользователя и его команды. Используйте это, чтобы принимать решения о масштабировании при высокой загрузке.

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

Пример проверки масштабирования:

const summary = await response.json();const team = summary.teamSummary;if (team && team.totalConnected > 0) {  const utilization = team.inUse / team.totalConnected;  if (utilization >= 0.9) {    // Масштабирование вверх: подготовьте дополнительных воркеров  }}

Получить воркер по ID

GET/v0/private-workers/{id}

Возвращает воркер из пула по его ID.

Параметры пути

id строка

Уникальный идентификатор воркера (например, pw_123).
curl --request GET \  --url "https://api.cursor.com/v0/private-workers/pw_123" \  -u "$CURSOR_API_KEY:"

Список пулов

GET/v0/private-workers/pools

Список постоянных пулов для команды аутентифицированного сервисного аккаунта. Пулы остаются зарегистрированными после отключения последнего воркера, поэтому вы можете отслеживать fleet, масштабируемые до нуля, и определять, когда нужно выделить ресурсы.

Параметры запроса

scope строка (необязательно)

Фильтрация по области видимости списка пулов. Одно из значений: all, team_pool или personal.

includeStale логическое значение (необязательно, по умолчанию: false)

Если true, включать пулы, помеченные как устаревшие после длительного бездействия.

Поля ответа

pools массив

Зарегистрированные пулы. Каждая запись включает:
  • scope строка — Область владения пулом (user или team).
  • ownerId целое число — ID пользователя или команды, которым принадлежит пул в этой области видимости.
  • poolName строка — Имя пула (например, default или gpu).
  • connectedWorkerCount целое число — Воркеры, подключённые к этому пулу.
  • inUseWorkerCount целое число — Подключённые воркеры, которым сейчас назначен Agent. Незанятые ресурсы: connectedWorkerCount - inUseWorkerCount.
  • firstSeenAtMs, lastSeenAtMs целое число — Время первого и последнего обнаружения в миллисекундах Unix.
  • isStale логическое значение — Указывает, помечен ли пул как устаревший после длительного бездействия.
  • repoOwner, repoName, repoUrl строка (необязательно) — Метаданные репозитория, если пул привязан к репозиторию. Не включаются для пулов для любых репозиториев.
  • workerReadyTimeoutSeconds целое число — Количество секунд, в течение которых зарезервированный запрос ожидает повторного подключения офлайн-воркера этого пула до истечения резервирования. 0 означает, что последующий запрос для офлайн-воркера немедленно повторно получает воркер из пула.
curl --request GET \  --url "https://api.cursor.com/v0/private-workers/pools?scope=team_pool&includeStale=false" \  -u "$CURSOR_API_KEY:"

Ответ:

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

Запись sandbox поддерживает любой репозиторий: поля репозитория не включаются, а пул остаётся доступным для выбора даже при отсутствии подключённых воркеров.

Зарегистрировать пул

POST/v0/private-workers/pools

Зарегистрируйте постоянный пул, не запуская воркер. Это позволяет выбрать пул ещё до подключения первого воркера, например когда контроллер выделяет ресурсы по требованию. При запуске воркера с --pool пул регистрируется автоматически; эта конечная точка нужна только для предварительного создания пула.

Тело запроса

scope строка (обязательно)

Область владения пулом: user или team.

poolName строка (обязательно)

Имя регистрируемого пула (например, gpu).

repoOwner, repoName строка (необязательно)

Метаданные репозитория, если пул связан с ним. Укажите оба параметра или не указывайте ни один для пула для любого репозитория.

repoUrl строка (необязательно)

URL-адрес репозитория для отображения. Требуются repoOwner и repoName.

workerReadyTimeoutSeconds целое число (необязательно, по умолчанию: 0)

Количество секунд, в течение которых зарезервированный запрос ожидает повторного подключения офлайн-воркера из этого пула, прежде чем резервирование истечёт и запрос вернётся в очередь. Задайте это значение, если машины переходят в гибернацию между шагами и могут быть восстановлены. При значении 0 последующие запросы для офлайн-воркера немедленно повторно получают воркер из пула. Должно быть неотрицательным целым числом.

Поля ответа

registered логическое значение

Указывает, был ли зарегистрирован пул.
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"  }'

Ответ:

{  "registered": true}

Удалить пул

DELETE/v0/private-workers/pools

Выполните мягкое удаление постоянного пула, чтобы он больше не отображался в списках выбора пулов и в разделе Список пулов. Это не повлияет на воркеры, уже подключённые к пулу. Для пулов команды требуется администратор команды; для пользовательских пулов — их владелец.

Параметры запроса

scope строка (обязательно)

Область владения пулом: user или team.

pool_name строка (обязательно)

Имя удаляемого пула.

repo_owner строка (необязательно)

Владелец репозитория при удалении записи пула, привязанной к репозиторию.

repo_name строка (необязательно)

Имя репозитория при удалении записи пула, привязанной к репозиторию. Укажите repo_owner и repo_name вместе или не указывайте ни один из них для пула, доступного для любого репозитория.
curl --request DELETE \  --url "https://api.cursor.com/v0/private-workers/pools?scope=team&pool_name=sandbox" \  -u "$CURSOR_API_KEY:"

Ответ:

{  "deregistered": true}

Список ожидающих запросов пула

GET/v0/private-workers/pending-requests

Возвращает список запросов к пулу, которым ещё не назначен воркер. Используйте этот эндпоинт, чтобы масштабировать ресурсы, когда пользователи ждут доступного воркера пула, или вместе с Зарезервировать ожидающий запрос перед запуском эфемерного воркера.

Для пулов, настроенных с workerReadyTimeoutSeconds, в списке также отображаются записи со статусом «зарезервирован, но offline»: запросы, чей зарезервированный воркер находится offline, пока открыто окно переподключения. Такие записи содержат claimedWorkerId и wakeTimeoutMs, чтобы controller мог восстановить машину.

Для этого эндпоинта требуется API-ключ сервисного аккаунта. Он возвращает запросы команды, к которой относится ключ, и исключает запросы My Machines. Если область действия ключа ограничена конкретными репозиториями, передайте repository; репозиторий должен входить в разрешённую область действия ключа.

Ответ содержит streamCursor. Передайте его в Отслеживание ожидающих запросов пула, чтобы отслеживать изменения очереди в реальном времени после получения этого снимка.

Параметры запроса

limit число (необязательно)

Количество ожидающих запросов, которые нужно вернуть. По умолчанию: 50, максимум: 100.

pageToken строка (необязательно)

Курсор пагинации из предыдущего ответа. Токены страниц привязаны к фильтрам repository и pool, с которыми были выданы.

repository строка (необязательно)

Фильтрация по URL-адресу репозитория. Обязателен для API-ключей сервисных аккаунтов с областью действия, ограниченной репозиторием. Не указывайте для ожидающих запросов с любым репозиторием.

pool строка (необязательно)

Фильтрация по имени пула. Точное сравнение с учётом регистра со значением метки pool запроса. Не указывайте, чтобы вывести запросы для всех пулов команды.

Поля ответа

requests массив

Ожидающие запросы. Каждая запись содержит:
  • id строка — Идентификатор ожидающего запроса или агента (передайте в Зарезервировать или Освободить резервирование как id).
  • userId целое число — Идентификатор пользователя Cursor, создавшего запрос.
  • userEmail строка (необязательно) — Электронная почта пользователя, отправившего запрос, если доступна. Используйте её, чтобы выбрать закреплённые за пользователем ресурсы без дополнительного поиска.
  • serviceAccountId строка (необязательно) — Сервисный аккаунт, связанный с запросом, если указан.
  • repoOwner, repoName, repoUrl строка (необязательно) — Метаданные репозитория, если запрос предназначен для репозитория. Не указываются для запросов пула для любого репозитория.
  • labels массив — Метки запроса в виде пар { key, value } (включая repo= и pool=, если заданы).
  • createdAtMs целое число — Время создания запроса в миллисекундах Unix.
  • claimedWorkerId строка (необязательно) — Указывается в записях с зарезервированным, но офлайн-воркером: запрос зарезервирован этим воркером, который сейчас не в сети. Запустите воркер с этим идентификатором (CURSOR_AGENT_WORKER_ID), чтобы возобновить работу агента на его машине.
  • wakeTimeoutMs целое число (необязательно) — Количество миллисекунд, оставшихся в окне повторного подключения для зарезервированной, но отключённой записи. По истечении этого окна резервирование прекращает действовать, и запрос снова объявляется как незарезервированная запись.

nextPageToken строка (необязательно)

Курсор пагинации. Не указывается, если страниц больше нет. Чтобы измерить глубину очереди, пройдите все страницы и подсчитайте запросы.

streamCursor строка

Непрозрачная позиция для возобновления отслеживания ожидающих запросов пула. На всех страницах одного логического списка повторяется один и тот же streamCursor; начните отслеживание с него после завершения пагинации. Срок его действия истекает через пять минут после получения списка, в котором он был выдан.
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:"

Ответ:

{  "requests": [    {      "id": "bc-00000000-0000-0000-0000-000000000002",      "userId": 321,      "userEmail": "owner@acme.example",      "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"}

Если исходный URL-адрес репозитория содержит userinfo, repoUrl не включает встроенные учётные данные.

Отслеживание ожидающих запросов пула

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

Получайте события жизненного цикла ожидающих запросов через Server-Sent Events (SSE), чтобы контроллеры могли реагировать на изменения очереди без опроса.

Для этой конечной точки требуется API-ключ сервисного аккаунта. Контроллеры сначала получают список, а затем начинают отслеживание: вызовите List Pending Pool Requests, чтобы получить состояние очереди, сохраните streamCursor из ответа, затем начните отслеживание именно с этой позиции. Используйте одинаковые фильтры repository и pool для списка и отслеживания; курсоры привязаны к фильтрам, с которыми они были выданы.

Параметры запроса

cursor строка (обязательный)

streamCursor из ответа со списком или SSE id: последнего обработанного события. При повторном подключении нативный EventSource отправляет этот идентификатор в заголовке Last-Event-ID, который имеет приоритет над параметром запроса.

repository строка (необязательно)

Та же семантика, что и у List Pending Pool Requests. Обязателен для API-ключей сервисных аккаунтов, ограниченных репозиторием. Параметры пагинации в потоке не поддерживаются.

pool строка (необязательно)

Отслеживать только события этого пула. Точное совпадение с учетом регистра со значением метки pool запроса. Должен совпадать с фильтром, использованным при получении списка, выдавшего курсор. Не указывайте, чтобы отслеживать все пулы команды.

События

Отслеживание воспроизводит сохраненные переходы после курсора, а затем получает события в реальном времени. SSE id: каждого события — это курсор для возобновления после разрыва подключения.

  • created событие — Запрос добавлен в очередь, включая забранный, но отключенный запрос, для которого истекло окно повторного подключения и срок захвата. Полезная нагрузка: тот же объект запроса, что и в List Pending Pool Requests.
  • claimed событие — Воркер забрал запрос или офлайн-воркер повторно подключился и возобновил забранный им запрос. Полезная нагрузка: { id }.
  • claimed_offline событие — Для запроса, забранный воркер которого находится офлайн, поступило повторное сообщение. Полезная нагрузка: тот же объект запроса, что и в List Pending Pool Requests, включая claimedWorkerId и wakeTimeoutMs. Возобновите работу машины до истечения окна, иначе захват истечет и запрос будет повторно опубликован с новым событием created.
  • expired событие — Запрос покинул очередь, не будучи забранным. Полезная нагрузка: { id }.
  • heartbeat событие — Контрольная точка курсора без изменения состояния; отправляется примерно каждые 20 секунд при отсутствии событий в потоке. Полезная нагрузка: {}. Сигналы активности обновляют позицию возобновления неактивного отслеживания, но не продлевают срок действия курсора.

Срок действия курсора

Каждый курсор в цепочке отслеживания истекает через пять минут после получения списка, который его выдал. Сигналы активности и повторные подключения не продлевают этот срок. Когда курсор истекает или больше не входит в окно сохраненных событий, конечная точка возвращает HTTP 410 Gone с {"code": "cursor_expired"}: повторно получите список и начните отслеживание с нового streamCursor. Это штатная ситуация, а не ошибка. Заблаговременно повторно получайте список каждые пять минут со случайным отклонением, вместо того чтобы ждать 410, чтобы вызовы списка у множества контроллеров не синхронизировались.

Гарантии доставки

Доставка выполняется по принципу best-effort, а список является источником истины. События публикуются после фиксации каждого перехода с повторными попытками, но в редких случаях событие может быть потеряно и никогда не будет отправлено повторно. Между повторными получениями списка считайте события низколатентными подсказками: применяйте их идемпотентно (создавайте или обновляйте запросы created и claimed_offline, удаляйте запросы claimed и expired по id), а следующий список исправит любые расхождения. Событие claimed для запроса, которого вы не видели, не требует действий. Захват остается атомарным на стороне сервера независимо от вашего локального представления.

Не сохраняйте курсоры. Сервисный аккаунт может одновременно поддерживать не более четырех потоков; используйте один поток на контроллер и локально распределяйте события.

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:"

Пример стрима:

: connected

event: heartbeat
id: djQuY3Vyc29yLWNoZWNrcG9pbnQ
data: {}

event: created
id: djQuY3Vyc29yLWFmdGVyLWNyZWF0ZWQ
data: {"id":"bc-00000000-0000-0000-0000-000000000002","userId":321,"userEmail":"owner@acme.example","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"}

Цикл контроллера:

  1. Получите список ожидающих запросов до завершения и замените локальное представление результатом. Сохраните streamCursor из ответа.
  2. Откройте поток наблюдения с ?cursor=<streamCursor> и применяйте события к локальному представлению. Отслеживайте id: последнего обработанного события.
  3. При отключении переподключитесь, передав идентификатор последнего события в ?cursor=, или используйте нативный EventSource, который автоматически отправит его как Last-Event-ID.
  4. При HTTP 410 Gone вернитесь к шагу 1 и снова получите список.

Зарезервировать ожидающий запрос

POST/v0/private-workers/claim

Зарезервируйте ожидающий запрос пула для конкретного воркера до его запуска. Контроллеры используют этот метод для атомарного распределения работы между репликами: получите список ожидающих запросов пула в собственной инфраструктуре, зарезервируйте один из них, а затем запустите воркер со стабильным идентификатором, соответствующим резервированию.

Повторное резервирование при наличии активного резервирования отклоняется. Сначала освободите резервирование, затем зарезервируйте новый workerId.

Для этой конечной точки требуется API-ключ сервисного аккаунта.

Тело запроса

id string (обязательно)

Идентификатор ожидающего запроса. То же значение, что и id из Списка ожидающих запросов пула в собственной инфраструктуре.

workerId string (обязательно)

Идентификатор воркера, резервируемый для запроса. Запустите воркер с тем же идентификатором через CURSOR_AGENT_WORKER_ID (или скрытый флаг --worker-id), чтобы bridge зарегистрировал зарезервированный идентификатор.
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"  }'

Ответ:

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

После успешного резервирования запустите воркер с зарезервированным идентификатором:

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

Освободить резервирование

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

Снимает долгосрочную заявку, привязывающую Agent к self-hosted воркеру. После освобождения Cursor перестаёт отдавать предпочтение этой машине для Agent.

Заявка — это рекомендация для маршрутизации, а не состояние активного процесса. Освобождение не проверяет, подключён ли воркер. Ожидающий последующий запрос возвращается в очередь пула при следующем планировании. Подключённый воркер без помех завершает текущий шаг. Сразу после освобождения другой воркер может заявить права на того же Agent.

Повторный вызов Зарезервировать ожидающий запрос, пока существует активная заявка, отклоняется. Сначала освободите заявку, затем заявите новый workerId.

--idle-release-timeout (переменная среды CURSOR_WORKER_IDLE_RELEASE_TIMEOUT) завершает работу CLI воркера после простоя. Эта конечная точка только снимает заявку на маршрутизацию.

Для этой конечной точки требуется API-ключ сервисного аккаунта.

Параметры пути

id string

ID ожидающего запроса / Agent. То же значение, что и id в Зарезервировать ожидающий запрос. Тело запроса отсутствует.
curl --request POST \  --url "https://api.cursor.com/v0/private-workers/claims/bc-00000000-0000-0000-0000-000000000002/release" \  -u "$CURSOR_API_KEY:"

Ответ:

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

HTTP 404 означает, что активной заявки нет: она уже освобождена, истекла или была принята другим воркером. Не повторяйте запрос при 404.

Конечные точки метаданных

Информация об API-ключе

GET/v1/me

Возвращает информацию об API-ключе, используемом для аутентификации.

Поля ответа

apiKeyName string

Отображаемое имя API-ключа.

createdAt string

Дата и время создания API-ключа (ISO 8601).

userId integer (ключи с областью пользователя)

Числовой идентификатор пользователя Cursor, которому принадлежит API-ключ. Не указывается для ключей сервисного аккаунта / Team API キー, которые не привязаны к конкретному пользователю.

userEmail string (ключи с областью пользователя)

Адрес электронной почты владельца API-ключа.

userFirstName, userLastName string (ключи с областью пользователя)

Имя и фамилия владельца API-ключа, если они указаны.
curl --request GET \  --url https://api.cursor.com/v1/me \  -u YOUR_API_KEY:

Ответ (ключ с областью пользователя):

{  "apiKeyName": "Production API Key",  "userId": 42,  "createdAt": "2026-04-13T18:30:00.000Z",  "userEmail": "developer@example.com",  "userFirstName": "Alex",  "userLastName": "Rivera"}

Ответ (ключ сервисного аккаунта):

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

Список моделей

GET/v1/models

Возвращает рекомендуемые модели, которые можно передавать в поле model.id в запросе Create An Agent, а также параметры и варианты, доступные для каждой модели. Параметры модели используют ту же структуру model.params, что и в TypeScript SDK ModelSelection.

Поля ответа

Каждый элемент в items описывает одну модель:

id string

Передавайте это значение как model.id при создании агента.

displayName string

Понятное пользователю имя, которое отображается в интерфейсе Cursor.

description string (optional)

Краткое описание модели.

aliases array (optional)

Альтернативные идентификаторы, которые указывают на ту же модель (например, composer-latest).

parameters array (optional)

Определения параметров для каждой модели. У каждой записи есть id, необязательный displayName и массив values с допустимыми значениями { value, displayName? }. Используйте их для заполнения model.params в запросе на создание.

variants array (optional)

Конкретные комбинации id и params, которые поддерживает модель. У каждой записи есть массив params (он может быть пустым), displayName, необязательный description и необязательный флаг isDefault.
curl --request GET \  --url https://api.cursor.com/v1/models \  -u YOUR_API_KEY:

Ответ:

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

Список репозиториев GitHub

GET/v1/repositories

Возвращает список репозиториев GitHub, доступных аутентифицированному пользователю через установленное приложение GitHub App Cursor.

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

Ответ:

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