Смотри, чего нашел!

Есть ли API у Cursor и как им пользоваться

Короткий ответ: да. Публичный API Cursor — это не «управление окном редактора», а запуск того же агента, что в IDE, CLI и веб-приложении. Public beta, контракт ещё может меняться.

Три рабочих поверхности:

1. SDK — TypeScript (@cursor/sdk) и Python (cursor-sdk). Один интерфейс для local и cloud.
2. REST Cloud Agents API — https://api.cursor.com/v1/... для HTTP и языков без SDK.
3. CLI — команда agent в терминале и CI (-p / print-режим).

Модель всегда хостится у Cursor. «Local» значит: цикл агента и файлы на вашей машине, не локальная LLM.

Ключ и биллинг

• Ключ: Cursor Dashboard → API Keys или service account в Team Settings.
• Переменная: CURSOR_API_KEY (значение вида cursor_... / crsr_...).
• User-ключ биллится на план пользователя, service account — на команду.
• Team Admin API keys пока не поддерживаются.
• Расход как у IDE / Cloud Agents; в дашборде usage помечается тегом SDK.

export CURSOR_API_KEY="cursor_..."

Что выбрать

• Скрипт, бот, CI, оркестрация из кода — SDK
• Другой язык / минимальный HTTP — REST /v1/agents
• Хук, shell, одноразовый промпт в пайплайне — CLI agent -p "..."
• Долгий джоб, PR из VM Cursor — Cloud runtime (cloud: { repos })
• Правки в текущем checkout — Local runtime (local: { cwd })

В Cursor: skill /sdk. Облачные запуски из SDK в UI: Filter → Source → SDK.

SDK: установка

TypeScript — Node.js 22.13+. Имя пакета строго @cursor/sdk (без @ пакета нет).

npm install @cursor/sdk

Python:

pip install cursor-sdk

Документация:

• TypeScript SDK
• Python SDK
• Анонс SDK

Модель по умолчанию для интеграций: composer-2.5. Список доступных: Cursor.models.list(). Для local модель обязательна; лучше всегда передавать явно.

Три паттерна вызова

1. One-shot — Agent.prompt(...). Скрипт/CI, без follow-up. Сам освобождает ресурсы.

TypeScript:

import { Agent } from "@cursor/sdk";
const result = await Agent.prompt("Refactor src/utils.ts for readability", {
apiKey: process.env.CURSOR_API_KEY!,
model: { id: "composer-2.5" },
local: { cwd: process.cwd() },
});
console.log(result.status, result.result);

Python:

import os
from cursor_sdk import Agent, AgentOptions, LocalAgentOptions
result = Agent.prompt(
"Refactor src/utils.py for readability",
AgentOptions(
api_key=os.environ["CURSOR_API_KEY"],
model="composer-2.5",
local=LocalAgentOptions(cwd=os.getcwd()),
),
)
print(result.status, result.result)

2. Durable — Agent.create + agent.send. Стрим, несколько ходов, cancel.

TypeScript:

await using agent = await Agent.create({
apiKey: process.env.CURSOR_API_KEY!,
model: { id: "composer-2.5" },
local: { cwd: process.cwd() },
});
const run = await agent.send("Find the bug in src/auth.ts");
for await (const event of run.stream()) {
if (event.type === "assistant") {
for (const block of event.message.content) {
if (block.type === "text") process.stdout.write(block.text);
}
}
}
await run.wait();

Python:

import os
from cursor_sdk import Agent, LocalAgentOptions
with Agent.create(
model="composer-2.5",
api_key=os.environ["CURSOR_API_KEY"],
local=LocalAgentOptions(cwd=os.getcwd()),
) as agent:
run = agent.send("Find the bug in src/auth.py")
for message in run.messages():
if message.type == "assistant":
for block in message.message.content:
if block.type == "text":
print(block.text, end="")
run.wait()

3. Resume — Agent.resume(id). Префикс bc- = cloud, иначе local. Inline MCP при resume не сохраняются — передайте снова.

Всегда явно указывайте local или cloud. Если не указать ничего, SDK молча возьмёт local.

Cloud-пример (TS): cloud: { repos: [{ url: "https://github.com/org/repo", startingRef: "main" }] }, при необходимости autoCreatePR: true. В CI: skipReviewerRequest: true.

Ошибки и dispose

• Исключение CursorAgentError — запуск не начался (auth, сеть, конфиг). Смотрите isRetryable / is_retryable.
• result.status === "error" — ран выполнился и упал. Другой exit code.
• Стрим — наблюдение; wait() почти всегда обязателен.
• TS: await using agent. Python: with Agent.create(...) as agent:. Agent.prompt dispose делает сам.
• Перед стримом логируйте run.id и agent.agentId / agent.agent_id.

Python по умолчанию sync. Для серверов: AsyncClient.launch_bridge + AsyncAgent. Не смешивать sync и async клиенты в одном пути.

REST: Cloud Agents API

База: https://api.cursor.com. Auth: Basic (-u API_KEY:) или Bearer. Обзор и OpenAPI: Cloud Agents API.

Полезные эндпоинты v1:

• POST /v1/agents — создать агента и первый run
• GET /v1/agents — список
• GET /v1/agents/{id} — один агент
• POST /v1/agents/{id}/runs — следующий промпт
• GET /v1/agents/{id}/runs/{runId}/stream — стрим
• POST /v1/agents/{id}/runs/{runId}/cancel
• GET /v1/agents/{id}/usage
• GET /v1/models, GET /v1/repositories, GET /v1/me

Минимум:

curl --request POST \
--url https://api.cursor.com/v1/agents \
-u "$CURSOR_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" }]}'

v1 = durable agent + отдельные runs (не плоский v0). Webhooks в v1 ещё «coming soon»; у legacy v0 они есть.

Другие языки: SDK Bridge (ссылка из доков SDK).

CLI

Обзор CLI

irm 'https://cursor.com/install?win32=true' | iex
agent
agent -p "find and fix performance issues" --model "composer-2.5"

Интерактивно: agent. Автоматизация: -p. Режимы: agent / plan / ask. Сессии: agent ls, agent resume. В облако из чата: сообщение с & в начале.

Рядом с API, но не API редактора

• MCP — инструменты агента (документация MCP). На send/create передаются inline; override заменяет список целиком, не мержит.
• Hooks — .cursor/hooks.json. SDK их уважает, но не управляет. Hooks.
• Self-hosted pool — свои воркеры: Self-hosted pool.
• Расширения VS Code в Cursor работают (форк VS Code). Отдельного публичного API «двигать вкладки IDE» нет; официальный программный слой — агент.

Типичные ловушки

1. Забыли cloud — получили local без ошибки.
2. 401: пробелы в ключе, другой environment, нет доступа к репо для cloud.
3. Модель недоступна аккаунту — сначала Cursor.models.list() / GET /v1/models.
4. settingSources: "all" в сервисе подтянет чужие user/project settings; для сервиса обычно оставляют пусто.
5. После апгрейда @cursor/sdk перегоните typecheck: типы стрима меняются.

Ссылки одним списком

• TypeScript SDK
• Python SDK
• Cloud Agents REST
• CLI
• MCP
• Ключи в Dashboard
• npm: @cursor/sdk
• PyPI: cursor-sdk
• Cookbook и примеры — из раздела Cookbook в доке TypeScript SDK