Cursor Cloud Agents API: как пользоваться

Cursor Cloud Agents API — это public beta HTTP API, которым вы программно запускаете и управляете Cloud Agents на репозиториях. Базовый host: https://api.cursor.com. Канон: Cloud Agents API endpoints. Auth: Basic или Bearer с user/service API key из Dashboard → API Keys.

Обзор продукта — Cloud Agents; креды на VM — Secrets и OIDC; среда — Environment. Pillar: n8n / автоматизация.

Модель v1: agent + run

v1 разделяет durable agent и per-prompt run (вместо flatter v0). Create сразу ставит initial run в очередь и возвращает оба объекта. Webhooks для v1 «coming soon»; legacy v0 webhooks ещё в справочнике. API может меняться до GA — закладывайте retry и чтение OpenAPI.

Операция	Метод / путь	Зачем
Create agent	POST /v1/agents	Создать агента + initial run
List agents	GET /v1/agents	Список (limit default 20, max 100)
Models	GET /v1/models	Допустимые model.id и params
Auth	Basic / Bearer	User или service account API key

Сверка: cursor.com/docs/cloud-agent/api/endpoints (проверка 2026-09-19). Public beta — поля могут расширяться.

Минимальный create

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" },
    "repos": [{ "url": "https://github.com/your-org/your-repo", "startingRef": "main" }],
    "autoCreatePR": true
  }'

Обязателен prompt.text. Без repos и без named cloud env получите no-repo агента. Максимум 20 репозиториев. workOnCurrentBranch: false (default) пушит в новую ветку cursor/...; true — в startingRef / head PR.

env: cloud, pool, machine

• env.type: cloud + optional name — Cursor-hosted VM / named environment.
• pool / machine — ваши workers; unknown pool name → 400, а не бесконечная очередь.
• Named cloud environment взаимно исключает явный список repos.

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

Полезные поля create

• model.id + model.params из GET /v1/models (иначе default user → team → system).
• mcpServers до 50: http/sse/stdio; remote headers/OAuth; stdio с command/env.
• customSubagents до 20; имена не должны бить built-ins (explore, debug, shell, computerUse…).
• mode: agent (default) или plan.
• envVars: session secrets до 50, имена не с PREFIX CURSOR_; beta, может silently ignore.
• agentId bc-… для идемпотентности; нельзя вместе с envVars.
• Картинки в prompt: ≤5, ≤15 MB, png/jpeg/gif/webp.

Что вернётся

В ответе: agent.id (bc-…), status, url на cursor.com/agents/…, latestRunId; run.id со статусом вроде CREATING. Дальше поллите list/get endpoints из OpenAPI (не выдумываем недокументированные поля).

Маршрут на один вечер

1. Создайте API key в Dashboard → API Keys (не коммитьте в git).
2. GET /v1/models — зафиксируйте id для вашего тарифа.
3. POST /v1/agents на тестовый репо с узким prompt и autoCreatePR.
4. Откройте agent.url, проверьте ветку/PR и artifacts.
5. Для продакшена добавьте spend alerts / usage limits и OIDC вместо long-lived cloud keys на VM.

Типичные ошибки

• Путать API key Cloud Agents API с OIDC socket JWT на VM.
• Жёстко кодить model.id без GET /v1/models.
• Unknown pool name и ожидание «просто подождёт» — будет 400.
• Считать, что envVars всегда включены: beta может silently ignore.
• Публиковать hard ₽ за API call — тарификация через usage модели + лимиты кабинета.

FAQ: Cursor Cloud Agents API

Вывод

Cloud Agents API — beta-вход для CI и ботов: POST /v1/agents, auth API key, модель agent+run. Среду и secrets готовьте до массовых вызовов; cloud roles на VM лучше через OIDC. Обзор продукта и соседние ноды кластера — в связанных лонгридах.