Cloud Agents API

公开测试版

Cloud Agents API v1 目前处于公开测试阶段。API 可能会在正式发布前发生变化。

Cloud Agents API 可让你以编程方式启动和管理处理你的仓库的云端代理。

Cloud Agents API 同时接受 Basic 和 Bearer 身份验证。在 Cursor Dashboard → API Keys 中生成用户 API 密钥，或使用服务账户 API 密钥。
有关身份验证方法、速率限制和最佳实践的详细信息，请参阅 API 概览。
查看完整的 OpenAPI 规范，了解详细的架构和示例。
Webhooks 即将推出。旧版 v0 API 仍支持该功能——请参阅 Webhooks。

从 v0 迁移？

此 API 将工作拆分为持久化智能体和按提示词划分的各次运行，取代了更扁平的 v0 接口。旧版 v0 参考仍可用。

端点

创建代理

POST/v1/agents

创建一个云端代理并立即将其初始运行加入队列。响应同时返回持久化的 agent 和初始 run。

请求体

prompt 对象 (必填)

智能体的任务提示词，支持可选的图像附件。

prompt.text string (必填)

智能体的指令文本。

prompt.images 数组 (可选)

用于提示的图像输入。每个条目必须包含 data (base64 编码的字节，且必须包含 mimeType) 或 url (Cursor 可获取的 http 或 https URL) 之一。最多 5 张图像，每张不超过 15 MB。支持的 MIME 类型：image/png、image/jpeg、image/gif、image/webp。

model 对象 (可选)

模型选择。省略此字段将使用已配置的默认值。省略时，Cursor 会先解析您的用户默认模型，再解析团队默认模型，最后使用系统默认模型。

model.id string (若提供 model 则必填)

由 GET /v1/models 返回的明确模型 ID (例如 claude-4-sonnet-thinking) 。

model.params 数组 (可选)

应用于本次运行的每个模型的参数，例如推理强度或上下文窗口大小。每一项包含 id 和 value。仅使用所选模型支持的参数 —— 调用 GET /v1/models 可查询有效的 id/params 组合。

name 字符串 (可选)

智能体的显示名称。最多 100 个字符。省略时，Cursor 会根据提示自动推导名称。

env 对象 (可选)

执行环境目标。使用命名的 cloud 环境，或路由到您自行托管的 pool 或 machine。在选择命名的 Cursor 托管环境时，不可与显式指定的 repos 一起使用。

env.type 字符串 (如果提供 env 则必填)

执行环境类型。cloud 使用 Cursor 托管的虚拟机；pool 和 machine 路由到您自己的 worker。

env.name 字符串 (可选)

已命名的 Cursor 托管环境、用量池或计算机名称。对于 env.type: "pool"，此处为用量池名称 (省略时默认为 default) 。未知的用量池名称会返回 400，而不会一直排队等待。

repos 数组 (可选)

仓库配置。与已命名的云环境互斥。省略 repos 和 env 可启动无仓库代理。当 env.type 为 pool 时，也可省略 repos 以指向任意仓库池。最多 20 个仓库。

repos[0].url 字符串 (必填)

GitHub 代码仓库 URL (例如 https://github.com/your-org/your-repo) 。每个仓库条目均为必填项，包��在提供 prUrl 时。

repos[0].startingRef 字符串 (可选)

用作起点的分支名称或提交 SHA。提供 prUrl 时会被忽略。

repos[0].prUrl 字符串 (可选)

GitHub 拉取请求 URL。提供后，代理将作用于该 PR 的仓库和分支；startingRef 将被忽略。同一 repos 条目中仍须设置 url。

workOnCurrentBranch 布尔值 (可选，默认：false)

当值为 false (默认) 时，Cursor 会将提交推送到基于 repos[0].startingRef 自动生成的新分支 (cursor/...) (如果设置了 prUrl，则基于 PR 的基准引用) 。当值为 true 时，Cursor 会直接推送到该起始引用——对于非 PR 创建，即您在 startingRef 中传入的分支；对于使用 prUrl 创建，即该 PR 的 head 分支。代理推送的分支会显示在代理的 git.branches[] 中。

autoCreatePR 布尔值 (可选)

运行完成后，Cursor 是否应创建拉取请求。

skipReviewerRequest 布尔值 (可选)

当 Cursor 打开 PR 时，是否跳过将用户添加为审阅者的请求。仅在 autoCreatePR 为 true 时适用。

envVars 对象 (可选)

云端代理的会话范围环境变量。值在静态存储时加密，会注入到代理的 shell 中，并随代理一起删除。最多 50 条；名称最长 255 字节 (不能以 CURSOR_ 开头) ，值最长 4096 字节。不能与客户端提供的 agentId 一起使用。

Beta： envVars 正在逐步推出。如果您的账户尚未启用该功能，创建时会静默忽略该字段而不会导致请求失败——在生产环境中依赖它之前，请在代理首次运行时通过检查代理的 shell 验证这些值是否存在。

mcpServers 数组 (可选)

供 agent 使用的内联 MCP 服务器定义。最多 50 台服务器。远程服务器支持 headers 或 OAuth auth；stdio 服务器在云端 VM 内运行，可接收 env。服务器名称必须唯一。

mcpServers[0].name string (必填)

向智能体公开的 MCP 服务器名称。

mcpServers[0].type string (可选)

传输类型：http、sse 或 stdio。对于带有 url 的远程服务器，默认为 http；对于带有 command 的服务器，默认为 stdio。

mcpServers[0].url string (远程 MCP 必填)

远程 MCP 服务器的 HTTP 或 HTTPS URL。URL 中不得包含用户名或密码。

mcpServers[0].command 字符串 (stdio MCP 必填)

在云代理虚拟机内启动 stdio MCP 服务器的命令。使用 args 和 env 传入参数和运行时机密。

customSubagents 数组 (可选)

定义主智能体在运行期间可委派的自定义子智能体。最多 20 个子智能体。每个条目需要 name、description 和 prompt，可选包含 model (模型 ID 字符串、ModelSelection 对象或 "inherit") 。名称必须唯一，且不能与内置名称冲突 (如 explore、debug、shell、computerUse 等) 。

mode 字符串 (可选，默认值：agent)

智能体首次运行时的初始对话模式。plan 在编码前先探索并起草方案 (Plan 模式) ；agent 直接实施更改。

agentId string (可选)

由客户端提供的 agent 标识符，格式为 bc-<uuid>。适用于幂等创建流程——对相同的 agentId 重复发送 POST 请求将返回 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"  }}

列出agents

GET/v1/agents

列出已认证用户的agents，按最新优先排序。

查询参数

limit number (可选)

返回的agents数量。默认值：20，最大值：100。

cursor string (可选)

上一响应中 nextCursor 返回的分页游标。

prUrl string (可选)

按 GitHub PR URL 筛选agents。

includeArchived boolean (可选，默认值：true)

是否在响应中包��已归档的agents。

列表项仅包含持久标识字段。调用 GET /v1/agents/{id} 获取完整记录 (repos、workOnCurrentBranch、autoCreatePR 等) 。

当没有更多页面时，响应中会省略 nextCursor——不会将其作为 null 返回。请将其缺失视为“没有更多结果”。

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

获取智能体

GET/v1/agents/{id}

获取智能体的持久元数据。执行状态存储在运行中——获取 latestRunId，然后调用获取某次运行以读取运行状态。

路径参数

id string

智能体的唯一标识符 (例如 bc-00000000-0000-0000-0000-000000000001) 。

响应字段

status string

智能体生命周期状态。控制器使用它来决定机器是否必须保持运行：

ACTIVE — 某个轮次正在运行、等待后台工作，或即将开始。保持智能体的机器运行。
IDLE — 上一个轮次已完成，并且接受后续请求。智能体的机器可以休眠或创建快照。以可恢复错误结束的运行也会报告 IDLE；运行级错误详情保留在获取某次运行中。
ARCHIVED — 智能体已被归档或已过期。终止状态；声明结束，工作区状态可以删除。

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": "添加包含设置说明的 README",  "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

向现有的活动智能体发送后续提示词。新运行会沿用该智能体当前的对话和工作区状态。

每个智能体同一时间只能有一个活动运行。如果在另一个运行处于 CREATING 或 RUNNING 状态时调用此接口，会返回 409 agent_busy。请等待现有运行结束，或将其取消。

路径参数

id string

智能体的唯一标识符 (例如 bc-00000000-0000-0000-0000-000000000001) 。

请求体

prompt object (必填)

后续提示词，可包含可选图像。

prompt.text string (必填)

后续指令文本。

prompt.images array (可选)

用于后续提示的输入图像。每个条目必须包含 data (base64 编码的字节，且必须提供 mimeType) 或 url。最多 5 张图像，每张最大 15 MB。支持的 MIME 类型：image/png、image/jpeg、image/gif、image/webp。

mcpServers array (可选)

此后续运行的内联 MCP 服务器定义。提供后，会替换此次运行在创建时内联配置的所有 MCP 服务器。省略则保留智能体当前的 MCP 配置。

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": "Also add troubleshooting steps"    },    "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

列出某个智能体的运行，按最新优先排序。

路径参数

id string

智能体的唯一标识符。

查询参数

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

智能体的唯一标识符。

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 (when a branch has been pushed)

智能体当前已推送的分支和 PR。git.branches[] 包含 { repoUrl, branch?, prUrl? } 条目——每个条目对应智能体已推送的一个分支 (堆叠式智能体会生成多个) 。

这是按智能体维度的状态，不是按运行维度。 同一智能体上的每次运行都会返回相同的 git 快照。使用智能体的 latestRunId 或 SSE 流将工作归因到特定运行。

repoUrl 返回时不包含 scheme (例如 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

流式传输某次运行的服务器发送事件 (SSE) 。该流仅针对所请求的运行，不会重放之前运行的事件。

事件类型

status — 运行状态更新。负载：{ runId, status }。
assistant — 助手文本增量。负载：{ text }。
thinking — 思考文本增量。负载：{ text }。
tool_call — 工具调用状态更新。负载：{ callId, name, status, args?, result?, truncated? }。
interaction_update — 与上述简化事件一同发出的可选增强事件。负载与 TypeScript SDK 使用的 InteractionUpdate 结构一致，子类型包括 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 是助手的最终回复，durationMs 是以毫秒为单位的实际运行时长，git 与 Run.git 保持一致 (是智能体当前已推送的分支，而不只是此次运行的分支) 。
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，且无法恢复。若要继续对话，请在同一个智能体上创建新的运行。

如果取消的运行已处于最终状态，或从未处于活动状态，则会返回 409 run_not_cancellable。

路径参数

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

获取智能体用量

GET/v1/agents/{id}/usage

获取某个智能体的 token 用量，并按每次运行分别统计。响应会汇总该智能体上所有运行的用量，并列出每次运行各自的用量。Token 用量与团队 usage events 接口报告的 tokenUsage 一致。

Path Parameters

id string

智能体的唯一标识符 (例如 bc-00000000-0000-0000-0000-000000000001) 。

Query Parameters

runId string (optional)

将响应限定为单次运行 (例如 run-00000000-0000-0000-0000-000000000001) 。省略时，将返回该智能体上所有运行的用量。未知的 runId 会返回 404 run_not_found。

Response Fields

totalUsage object

返回的所有运行汇总后的 token 用量。包含与每次运行的 usage object 相同的字段。

runs array

按运行划分的用量，每次运行对应一条记录 (设置了 runId 时则只有一条) 。每个 object ��含：

id string - 运行标识符 (例如 run-00000000-0000-0000-0000-000000000001) 。
usageUuid string (optional) - 该次运行的内部用量标识符。如果该次运行尚未记录任何用量，则会省略。
usage object - 此次运行的 token 用量：
- inputTokens number - 消耗的输入 tokens。
- outputTokens number - 生成的输出 tokens。
- cacheWriteTokens number - 写入缓存的 tokens。
- cacheReadTokens number - 从缓存读取的 tokens。
- totalTokens number - 上述四项 token 计数之和。

没有任何已记录 token 用量的运行，会在所有字段中返回 0。尚未产生用量的运行仍会显示在 runs 中，以便你持续跟踪。

# 智能体的所有运行记录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/ 目录的路径。

将此处返回的 path 值直接传给下载产物。v1 路径是相对路径；不接受 v0 的绝对路径 (/opt/cursor/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

获取某个特定产物的临时预签名 S3 URL，有效期为 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

归档智能体。已归档的智能体仍可读取，但在取消归档前无法接受新的运行。适用于可撤销的“软删除”流程。

归档操作是幂等的——对已归档的智能体再次归档会返回 200，且不会有任何变化。调用前无需检查当前状态。

路径参数

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

取消归档智能体，使其能够再次接受新的运行。

取消归档操作是幂等的——对已处于活动状态的智能体调用该操作会返回 200，且不会有任何变化。

路径参数

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

Worker Token

创建用户级 Worker Token

POST/v1/sub-tokens

为 Worker 创建一个有效期为 1 小时的用户级 token，使其能够以活跃团队成员身份运行。

需要提供一个智能体作用域的团队服务账户 API 密钥。用户级 token 不能用于签发其他用户级 token。

返回的 token 会在 1 小时后过期，且无法自行刷新。需要为正在运行的 Worker 刷新时，请使用服务账户 API 密钥重新签发一个新 token。

请求体

请准确指定以下其中一项来标识目标用户：

forUserEmail string (可选)

活跃团队成员的电子邮件地址。不区分大小写。

forUserId integer (可选)

活跃团队成员的 Cursor 数字用户 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 '{    "forUserEmail": "alice@company.com"  }'

按用户 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}

worker 和用量池

监控 worker 利用率，并为您的用量池实现自动伸缩。持久用量池会在最后一个 worker 断开连接后保持注册，因此您可以缩减至零，并在出现待处理请求时恢复容量。

端点路径沿用较早的 private-workers 名称；它们指的是同一批worker。

使用该用量池的服务账户 API 密钥，通过 Basic 认证或 Bearer token 进行认证。其他类型的 API 密钥将被拒绝。

列出 worker

GET/v0/private-workers

列出已认证服务账户所属团队的用量池 worker，按连接时间倒序排列。

查询参数

status string (可选，默认值：all)

按 worker 状态筛选。可选值为 all、in_use 或 idle。

scope string (可选，默认值：all)

按 worker 范围筛选。可选值为 all、team_pool 或 personal。

limit integer (可选，默认值：50)

每页结果数。范围：1 至 100。

pageToken string (可选)

分页游标。传入上一响应中的 nextPageToken。

响应字段

workers array

已连接的 worker。每个条目包括：

workerId string — 唯一的 worker 标识符。自动生成的 ID 为 UUID；使用 CURSOR_AGENT_WORKER_ID 启动的 worker 则报告该自定义 ID。
isInUse boolean — worker 当前是否已分配智能体。
repoOwner, repoName string — worker 注册 git remote 时的主代码仓库元数据。任意仓库 worker 的值为空字符串。
repoUrl string (可选) — 主代码仓库 URL。任意仓库 worker 不返回该字段。
workspaceRootPath string — worker 上的主工作区路径。
connectedAtMs integer — 以 Unix 毫秒表示的连接时间。
userId integer — 所属用户 ID。使用服务账户密钥认证的 worker 为 0。
teamId integer (可选) — 团队用量池 worker 的团队 ID。
serviceAccountId string (可选) — 对该 worker 进行认证的服务账户。
activeBcId string (可选) — 使用中时，当前在 worker 上运行的智能体 ID。
name string (可选) — worker 显示名称 (--name，默认值为机器主机名) 。

totalCount integer

所有页面中符合筛选条件的 worker 总数。

nextPageToken string (可选)

用于 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}

获取 worker 摘要

GET/v0/private-workers/summary

返回已通过身份验证的用户及其团队中已连接和正在使用的 worker 数量。可在利用率较高时用它触发伸缩决策。

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) {    // 扩容：预配额外的 worker  }}

按 ID 获取 worker

GET/v0/private-workers/{id}

根据 ID 获取单个用量池 worker。

路径参数

id string

worker 的唯一标识符 (例如 pw_123) 。

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

列出用量池

GET/v0/private-workers/pools

列出已认证服务账户所属团队的持久用量池。即使最后一个 worker 断开连接，用量池仍会保持注册状态，因此您可以监控缩容至零的机群，并决定何时预配容量。

查询参数

scope string (可选)

按用量池列表的范围筛选。可选值为 all、team_pool 或 personal。

includeStale boolean (可选，默认值：false)

设为 true 时，包含因长期未活动而标记为过期的用量池。

响应字段

pools array

已注册的用量池。每个条目包含：

scope string — 用量池的归属范围 (user 或 team) 。
ownerId integer — 该范围对应的所属用户或团队 ID。
poolName string — 用量池名称 (例如 default 或 gpu) 。
connectedWorkerCount integer — 当前连接到此用量池的 worker 数量。
inUseWorkerCount integer — 当前已分配智能体的已连接 worker 数量。空闲容量为 connectedWorkerCount - inUseWorkerCount。
firstSeenAtMs, lastSeenAtMs integer — 首次和最后一次发现的时间，以 Unix 毫秒表示。
isStale boolean — 用量池是否因长期未活动而标记为过期。
repoOwner, repoName, repoUrl string (可选) — 用量池关联仓库时的仓库元数据。对于适用于任意仓库的用量池，这些字段会被省略。
workerReadyTimeoutSeconds integer — 已认领请求在认领过期前等待此用量池的离线 worker 重新连接的秒数。0 表示离线 worker 的后续请求会立即从用量池重新获取。

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 条目是适用于任意仓库的用量池：仓库字段会被省略，即使没有已连接的 worker，该用量池仍可供选择。

注册用量池

POST/v0/private-workers/pools

注册持久用量池，无需启动 worker。可在任何 worker 连接前让用量池可供选择，例如控制器按需预配容量时。使用 --pool 启动 worker 会自动注册该用量池；仅需预先创建用量池时才需要调用此端点。

请求体

scope string (必填)

用量池归属范围。取值为 user 或 team。

poolName string (必填)

要注册的用量池名称 (例如 gpu) 。

repoOwner, repoName string (可选)

用量池关联仓库时的仓库元数据。请同时提供两者；适用于任意仓库的用量池则同时省略两者。

repoUrl string (可选)

用于显示的仓库 URL。需要提供 repoOwner 和 repoName。

workerReadyTimeoutSeconds integer (可选，默认值：0)

已认领的请求会等待此用量池中的离线 worker 重新连接的秒数，超时后认领过期，请求返回队列。当机器可在轮次之间休眠且能够恢复时，请设置此值。设为 0 时，离线 worker 的后续请求会立即从用量池重新获取 worker。必须为非负整数。

响应字段

registered boolean

用量池是否已注册。

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

注销 (软删除) 持久用量池，使其不再显示在用量池选择器或列出用量池中。当前连接到该用量池的 worker 不受影响。团队用量池需要团队管理员权限；用户用量池需要其所有者权限。

查询参数

scope string (必填)

用量池的归属范围。取值为 user 或 team。

pool_name string (必填)

要注销的用量池名称。

repo_owner string (可选)

注销仓库范围的用量池记录时的仓库所有者。

repo_name string (可选)

注销仓库范围的用量池记录时的仓库名称。请同时提供 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

列出尚未分配给 worker 的用量池请求。当用户正在等待可用的用量池 worker 时，可使用此端点扩展容量；也可在启动临时 worker 前，结合认领待处理请求使用。

对于配置了 workerReadyTimeoutSeconds 的��量池，列表中还会显示已认领但离线的条目：即在重新连接窗口开启期间，所认领的 worker 处于离线状态的请求。这些条目会携带 claimedWorkerId 和 wakeTimeoutMs，以便 controller 能够唤醒该机器。

此端点需要服务账户 API 密钥。它返回该密钥所属团队的请求，不包含我的机器 (My Machines) 请求。如果该密钥的范围限定为特定仓库，请传入 repository；该仓库必须在密钥的允许范围内。

响应包含 streamCursor。将其传递给监视待处理用量池请求，即可在此快照之后实时跟踪队列变化。

查询参数

limit number (可选)

要返回的待处理请求数量。默认值：50；最大值：100。

pageToken string (可选)

上一响应返回的分页游标。页面 token 与生成它们时使用的 repository 和 pool 筛选条件绑定。

repository 字符串 (可选)

按仓库 URL 筛选。对于限定仓库范围的服务账户 API 密钥，此参数必填。若要获取任意仓库的待处理请求，则省略此参数。

pool 字符串 (可选)

按用量池名称筛选。与请求的 pool 标签进行精确的区分大小写匹配。省略则列出团队中所有用量池的请求。

响应字段

requests array

待处理请求。每个条目包括：

id string — 待处理请求 / 智能体 ID (作为 id 传递给认领或释放认领) 。
userId integer — 创建该请求的 Cursor 用户 ID。
userEmail string (可选) — 发起请求的用户的电子邮件 (如有)。可据此选择与用户关联的容量，无需额外查询。
serviceAccountId string (可选) — 与该请求关联的服务账户 (如有)。
repoOwner, repoName, repoUrl string (可选) — 请求以仓库为目标时的仓库元数据。任意仓库用量池请求中会省略。
labels array — 请求标签，以 { key, value } 键值对形式表示 (设置后会包含 repo= 和 pool=)。
createdAtMs integer — 请求创建时间，以 Unix 毫秒为单位。
claimedWorkerId string (可选) — 出现在已认领但离线的条目中：该请求已由此 worker 认领，但该 worker 当前离线。使用此 ID (CURSOR_AGENT_WORKER_ID) 启动 worker，以便在其机器上恢复智能体。
wakeTimeoutMs integer (可选) — 已认领但离线的条目在重新连接窗口内剩余的毫秒数。窗口到期后，认领将失效，该请求会作为未认领条目重新发布。

nextPageToken string (可选)

分页游标。没有更多页面时会省略。要衡量队列深度，请完成全部分页并统计请求数量。

streamCursor string

用于监视待处理用量池请求的不透明恢复位置。同一次逻辑列表的每一页都会返回相同的 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 密钥。控制器采用先列出后监控的方式：调用列出待处理用量池请求构建队列视图，保留响应中的 streamCursor，然后从该确切位置开始监控。列出和监控必须使用相同的 repository 和 pool 筛选条件；游标与生成它的筛选条件绑定。

查询参数

cursor string (必填)

列表响应中的 streamCursor，或最后一个已处理事件的 SSE id:。重新连接时，原生 EventSource 会将该 id 作为 Last-Event-ID 标头重新发送，其优先级高于查询参数。

repository 字符串 (可选)

语义与列出待处理用量池请求相同。对于仓库范围的服务账户 API 密钥，此项为必填。流不接受分页参数。

pool 字符串 (可选)

仅监控此用量池的事件。与请求的 pool 标签进行精确且区分大小写的匹配。必须与生成游标的列表所用筛选条件一致。省略此参数可监控团队中的所有用量池。

事件

监控会重放游标之后保留的状态转换，然后持续接收实时事件。每个事件的 SSE id: 都是连接中断后恢复时使用的游标。

created 事件 — 请求进入队列，包括已被认领但处于离线状态、重连窗口已过且认领已失效的请求。负载：与列出待处理用量池请求相同的请求对象。
claimed 事件 — worker 已认领该请求，或离线 worker 重新连接后恢复处理其已认领的请求。负载：{ id }。
claimed_offline 事件 — 已认领该请求的 worker 离线后收到后续消息。负载：与列出待处理用量池请求相同的请求对象，包括 claimedWorkerId 和 wakeTimeoutMs。在窗口到期前唤醒机器，否则认领将过期，并通过新的 created 事件重新发布该请求。
expired 事件 — 请求未被认领便离开队列。负载：{ id }。
heartbeat 事件 — 不含状态变化的游标检查点，在空闲流中约每 20 秒发送一次。负载：{}。心跳会推进空闲监控的恢复位置，但不会延长游标的生命周期。

游标生命周期

监控链中的每个游标都会在生成它的列表请求五分钟后过期。心跳和重新连接都不会延长其生命周期。当游标过期，或保留事件窗口不再覆盖该游标时，端点会返回 HTTP 410 Gone 和 {"code": "cursor_expired"}：重新列出，并从新的 streamCursor 开始监控。这是常规情况，并非错误路径。应按带抖动的五分钟定时器主动重新列出，而不是等到 410，以免一组控制器同时发起列表调用。

投递保证

投递为尽力而为，列表是事实依据。每次状态转换提交后都会发布事件，并进行重试，但极少数故障可能导致事件丢失，且丢失的事件不会重新投递。在两次重新列出之间，应将事件视为低延迟提示：以幂等方式应用它们 (upsert created 和 claimed_offline 请求，按 id 移除 claimed 和 expired 请求) ，并由下一次列表修正任何偏差。对于从未见过的请求，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"}

控制器循环：

列出所有待处理请求，并用结果更新本地视图。保留响应中的 streamCursor。
使用 ?cursor=<streamCursor> 建立 watch 连接，并将事件应用到本地视图。记录已处理的最新事件 id:。
断开连接后，使用最新事件 ID 作为 ?cursor= 重新连接；或者使用原生 EventSource，它会自动将其作为 Last-Event-ID 重新发送。
收到 HTTP 410 Gone 时，返回步骤 1，重新列出请求。

认领待处理请求

POST/v0/private-workers/claim

在指定 worker 启动前，为其预留一个待处理用量池请求。控制器通过此操作在多个副本之间以原子方式分配工作：读取待处理请求，认领其中一个，再使用与认领信息匹配的稳定 worker ID 启动 worker。

已存在有效认领时，第二次认领会被拒绝。请先释放认领，再认领新的 workerId。

此端点需要服务账户 API 密钥。

请求体

id string (必填)

待处理请求 ID。与列出待处理用量池请求返回的 id 值相同。

workerId string (必填)

为该请求预留的 worker ID。通过 CURSOR_AGENT_WORKER_ID (或隐藏的 --worker-id 标志) 使用相同 ID 启动 worker，以便 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"}

成功认领后，使用预留的 ID 启动 worker：

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

解除将智能体绑定到自托管 worker 的长期认领。释放后，Cursor 不再优先为该智能体选择该机器。

认领是一种路由建议，并非实时进程状态。释放不会检查 worker 是否已连接。等待中的后续请求会在下一个调度点返回用量池队列。已连接的 worker 会不受影响地完成当前轮次。释放后，其他 worker 可立即认领同一智能体。

如果存在有效认领，第二次认领待处理请求将被拒绝。请先释放，再认领新的 workerId。

--idle-release-timeout (环境变量 CURSOR_WORKER_IDLE_RELEASE_TIMEOUT) 会使 worker CLI 在空闲后退出。此端点仅解除路由认领。

此端点需要服务账户 API 密钥。

路径参数

id string

待处理请求 / 智能体 ID。与认领待处理请求中的 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 (用户级密钥)

API 密钥所有者的 Cursor 用户 ID (数字) 。对于 service-account / 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

返回可在 Create An Agent 的 model.id 字段中传入的推荐模型，以及每个模型支持的参数和变体。模型参数采用与 TypeScript SDK ModelSelection 中 model.params 相同的结构。

如需使用已配置的默认模型，请在请求体中完全省略 model。Cursor 会依次解析你的用户默认模型、团队默认模型，最后回退到系统默认值。

响应字段

items 中的每一项描述一个模型：

id string

创建智能体时，将此值作为 model.id 传入。

displayName string

显示在 Cursor UI 中、便于阅读的名称。

description string (optional)

模型的简短描述。

aliases array (optional)

映射到同一模型的别名 ID (例如 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

列出已通过身份验证的用户可通过 Cursor 的 GitHub App 安装访问的 GitHub 仓库。

此端点的速率限制非常严格。

请将请求频率限制为 每用户每分钟 1 次，以及 每用户每小时 30 次。

对于可访问大量仓库的用户，此请求可能需要几十秒才能返回响应。

请确保在无法获取此信息时也能妥善处理。

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

响应：

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

Cloud Agents API

公开测试版

Cloud Agents API v1 目前处于公开测试阶段。API 可能会在正式发布前发生变化。

Cloud Agents API 可让你以编程方式启动和管理处理你的仓库的云端代理。

Cloud Agents API 同时接受 Basic 和 Bearer 身份验证。在 Cursor Dashboard → API Keys 中生成用户 API 密钥，或使用服务账户 API 密钥。
有关身份验证方法、速率限制和最佳实践的详细信息，请参阅 API 概览。
查看完整的 OpenAPI 规范，了解详细的架构和示例。
Webhooks 即将推出。旧版 v0 API 仍支持该功能——请参阅 Webhooks。

从 v0 迁移？

此 API 将工作拆分为持久化智能体和按提示词划分的各次运行，取代了更扁平的 v0 接口。旧版 v0 参考仍可用。

端点

创建代理

POST/v1/agents

创建一个云端代理并立即将其初始运行加入队列。响应同时返回持久化的 agent 和初始 run。

请求体

prompt 对象 (必填)

智能体的任务提示词，支持可选的图像附件。

prompt.text string (必填)

智能体的指令文本。

prompt.images 数组 (可选)

model 对象 (可选)

模型选择。省略此字段将使用已配置的默认值。省略时，Cursor 会先解析您的用户默认模型，再解析团队默认模型，最后使用系统默认模型。

model.id string (若提供 model 则必填)

由 GET /v1/models 返回的明确模型 ID (例如 claude-4-sonnet-thinking) 。

model.params 数组 (可选)

name 字符串 (可选)

智能体的显示名称。最多 100 个字符。省略时，Cursor 会根据提示自动推导名称。

env 对象 (可选)

执行环境目标。使用命名的 cloud 环境，或路由到您自行托管的 pool 或 machine。在选择命名的 Cursor 托管环境时，不可与显式指定的 repos 一起使用。

env.type 字符串 (如果提供 env 则必填)

执行环境类型。cloud 使用 Cursor 托管的虚拟机；pool 和 machine 路由到您自己的 worker。

env.name 字符串 (可选)

repos 数组 (可选)

repos[0].url 字符串 (必填)

GitHub 代码仓库 URL (例如 https://github.com/your-org/your-repo) 。每个仓库条目均为必填项，包括在提供 prUrl 时。

repos[0].startingRef 字符串 (可选)

用作起点的分支名称或提交 SHA。提供 prUrl 时会被忽略。

repos[0].prUrl 字符串 (可选)

GitHub 拉取请求 URL。提供后，代理将作用于该 PR 的仓库和分支；startingRef 将被忽略。同一 repos 条目中仍须设置 url。

workOnCurrentBranch 布尔值 (可选，默认：false)

autoCreatePR 布尔值 (可选)

运行完成后，Cursor 是否应创建拉取请求。

skipReviewerRequest 布尔值 (可选)

当 Cursor 打开 PR 时，是否跳过将用户添加为审阅者的请求。仅在 autoCreatePR 为 true 时适用。

envVars 对象 (可选)

mcpServers 数组 (可选)

mcpServers[0].name string (必填)

向智能体公开的 MCP 服务器名称。

mcpServers[0].type string (可选)

传输类型：http、sse 或 stdio。对于带有 url 的远程服务器，默认为 http；对于带有 command 的服务器，默认为 stdio。

mcpServers[0].url string (远程 MCP 必填)

远程 MCP 服务器的 HTTP 或 HTTPS URL。URL 中不得包含用户名或密码。

mcpServers[0].command 字符串 (stdio MCP 必填)

在云代理虚拟机内启动 stdio MCP 服务器的命令。使用 args 和 env 传入参数和运行时机密。

customSubagents 数组 (可选)

mode 字符串 (可选，默认值：agent)

智能体首次运行时的初始对话模式。plan 在编码前先探索并起草方案 (Plan 模式) ；agent 直接实施更改。

agentId string (可选)

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

列出agents

GET/v1/agents

列出已认证用户的agents，按最新优先排序。

查询参数

limit number (可选)

返回的agents数量。默认值：20，最大值：100。

cursor string (可选)

上一响应中 nextCursor 返回的分页游标。

prUrl string (可选)

按 GitHub PR URL 筛选agents。

includeArchived boolean (可选，默认值：true)

是否在响应中包含已归档的agents。

列表项仅包含持久标识字段。调用 GET /v1/agents/{id} 获取完整记录 (repos、workOnCurrentBranch、autoCreatePR 等) 。

当没有更多页面时，响应中会省略 nextCursor——不会将其作为 null 返回。请将其缺失视为“没有更多结果”。

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

获取智能体

GET/v1/agents/{id}

获取智能体的持久元数据。执行状态存储在运行中——获取 latestRunId，然后调用获取某次运行以读取运行状态。

路径参数

id string

智能体的唯一标识符 (例如 bc-00000000-0000-0000-0000-000000000001) 。

响应字段

status string

智能体生命周期状态。控制器使用它来决定机器是否必须保持运行：

ACTIVE — 某个轮次正在运行、等待后台工作，或即将开始。保持智能体的机器运行。
IDLE — 上一个轮次已完成，并且接受后续请求。智能体的机器可以休眠或创建快照。以可恢复错误结束的运行也会报告 IDLE；运行级错误详情保留在获取某次运行中。
ARCHIVED — 智能体已被归档或已过期。终止状态；声明结束，工作区状态可以删除。

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": "添加包含设置说明的 README",  "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

向现有的活动智能体发送后续提示词。新运行会沿用该智能体当前的对话和工作区状态。

路径参数

id string

智能体的唯一标识符 (例如 bc-00000000-0000-0000-0000-000000000001) 。

请求体

prompt object (必填)

后续提示词，可包含可选图像。

prompt.text string (必填)

后续指令文本。

prompt.images array (可选)

mcpServers array (可选)

此后续运行的内联 MCP 服务器定义。提供后，会替换此次运行在创建时内联配置的所有 MCP 服务器。省略则保留智能体当前的 MCP 配置。

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": "Also add troubleshooting steps"    },    "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

列出某个智能体的运行，按最新优先排序。

路径参数

id string

智能体的唯一标识符。

查询参数

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

智能体的唯一标识符。

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 (when a branch has been pushed)

智能体当前已推送的分支和 PR。git.branches[] 包含 { repoUrl, branch?, prUrl? } 条目——每个条目对应智能体已推送的一个分支 (堆叠式智能体会生成多个) 。

repoUrl 返回时不包含 scheme (例如 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

流式传输某次运行的服务器发送事件 (SSE) 。该流仅针对所请求的运行，不会重放之前运行的事件。

事件类型

status — 运行状态更新。负载：{ runId, status }。
assistant — 助手文本增量。负载：{ text }。
thinking — 思考文本增量。负载：{ text }。
tool_call — 工具调用状态更新。负载：{ callId, name, status, args?, result?, truncated? }。
interaction_update — 与上述简化事件一同发出的可选增强事件。负载与 TypeScript SDK 使用的 InteractionUpdate 结构一致，子类型包括 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 是助手的最终回复，durationMs 是以毫秒为单位的实际运行时长，git 与 Run.git 保持一致 (是智能体当前已推送的分支，而不只是此次运行的分支) 。
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;  };}

恢复流

保留期

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

如果取消的运行已处于最终状态，或从未处于活动状态，则会返回 409 run_not_cancellable。

路径参数

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

获取智能体用量

GET/v1/agents/{id}/usage

Path Parameters

id string

智能体的唯一标识符 (例如 bc-00000000-0000-0000-0000-000000000001) 。

Query Parameters

runId string (optional)

将响应限定为单次运行 (例如 run-00000000-0000-0000-0000-000000000001) 。省略时，将返回该智能体上所有运行的用量。未知的 runId 会返回 404 run_not_found。

Response Fields

totalUsage object

返回的所有运行汇总后的 token 用量。包含与每次运行的 usage object 相同的字段。

runs array

按运行划分的用量，每次运行对应一条记录 (设置了 runId 时则只有一条) 。每个 object 包含：

id string - 运行标识符 (例如 run-00000000-0000-0000-0000-000000000001) 。
usageUuid string (optional) - 该次运行的内部用量标识符。如果该次运行尚未记录任何用量，则会省略。
usage object - 此次运行的 token 用量：
- inputTokens number - 消耗的输入 tokens。
- outputTokens number - 生成的输出 tokens。
- cacheWriteTokens number - 写入缓存的 tokens。
- cacheReadTokens number - 从缓存读取的 tokens。
- totalTokens number - 上述四项 token 计数之和。

没有任何已记录 token 用量的运行，会在所有字段中返回 0。尚未产生用量的运行仍会显示在 runs 中，以便你持续跟踪。

# 智能体的所有运行记录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/ 目录的路径。

将此处返回的 path 值直接传给下载产物。v1 路径是相对路径；不接受 v0 的绝对路径 (/opt/cursor/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

获取某个特定产物的临时预签名 S3 URL，有效期为 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

归档智能体。已归档的智能体仍可读取，但在取消归档前无法接受新的运行。适用于可撤销的“软删除”流程。

归档操作是幂等的——对已归档的智能体再次归档会返回 200，且不会有任何变化。调用前无需检查当前状态。

路径参数

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

取消归档智能体，使其能够再次接受新的运行。

取消归档操作是幂等的——对已处于活动状态的智能体调用该操作会返回 200，且不会有任何变化。

路径参数

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

Worker Token

创建用户级 Worker Token

POST/v1/sub-tokens

为 Worker 创建一个有效期为 1 小时的用户级 token，使其能够以活跃团队成员身份运行。

需要提供一个智能体作用域的团队服务账户 API 密钥。用户级 token 不能用于签发其他用户级 token。

返回的 token 会在 1 小时后过期，且无法自行刷新。需要为正在运行的 Worker 刷新时，请使用服务账户 API 密钥重新签发一个新 token。

请求体

请准确指定以下其中一项来标识目标用户：

forUserEmail string (可选)

活跃团队成员的电子邮件地址。不区分大小写。

forUserId integer (可选)

活跃团队成员的 Cursor 数字用户 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 '{    "forUserEmail": "alice@company.com"  }'

按用户 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}

worker 和用量池

端点路径沿用较早的 private-workers 名称；它们指的是同一批worker。

使用该用量池的服务账户 API 密钥，通过 Basic 认证或 Bearer token 进行认证。其他类型的 API 密钥将被拒绝。

列出 worker

GET/v0/private-workers

列出已认证服务账户所属团队的用量池 worker，按连接时间倒序排列。

查询参数

status string (可选，默认值：all)

按 worker 状态筛选。可选值为 all、in_use 或 idle。

scope string (可选，默认值：all)

按 worker 范围筛选。可选值为 all、team_pool 或 personal。

limit integer (可选，默认值：50)

每页结果数。范围：1 至 100。

pageToken string (可选)

分页游标。传入上一响应中的 nextPageToken。

响应字段

workers array

已连接的 worker。每个条目包括：

workerId string — 唯一的 worker 标识符。自动生成的 ID 为 UUID；使用 CURSOR_AGENT_WORKER_ID 启动的 worker 则报告该自定义 ID。
isInUse boolean — worker 当前是否已分配智能体。
repoOwner, repoName string — worker 注册 git remote 时的主代码仓库元数据。任意仓库 worker 的值为空字符串。
repoUrl string (可选) — 主代码仓库 URL。任意仓库 worker 不返回该字段。
workspaceRootPath string — worker 上的主工作区路径。
connectedAtMs integer — 以 Unix 毫秒表示的连接时间。
userId integer — 所属用户 ID。使用服务账户密钥认证的 worker 为 0。
teamId integer (可选) — 团队用量池 worker 的团队 ID。
serviceAccountId string (可选) — 对该 worker 进行认证的服务账户。
activeBcId string (可选) — 使用中时，当前在 worker 上运行的智能体 ID。
name string (可选) — worker 显示名称 (--name，默认值为机器主机名) 。

totalCount integer

所有页面中符合筛选条件的 worker 总数。

nextPageToken string (可选)

用于 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}

获取 worker 摘要

GET/v0/private-workers/summary

返回已通过身份验证的用户及其团队中已连接和正在使用的 worker 数量。可在利用率较高时用它触发伸缩决策。

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) {    // 扩容：预配额外的 worker  }}

按 ID 获取 worker

GET/v0/private-workers/{id}

根据 ID 获取单个用量池 worker。

路径参数

id string

worker 的唯一标识符 (例如 pw_123) 。

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

列出用量池

GET/v0/private-workers/pools

查询参数

scope string (可选)

按用量池列表的范围筛选。可选值为 all、team_pool 或 personal。

includeStale boolean (可选，默认值：false)

设为 true 时，包含因长期未活动而标记为过期的用量池。

响应字段

pools array

已注册的用量池。每个条目包含：

scope string — 用量池的归属范围 (user 或 team) 。
ownerId integer — 该范围对应的所属用户或团队 ID。
poolName string — 用量池名称 (例如 default 或 gpu) 。
connectedWorkerCount integer — 当前连接到此用量池的 worker 数量。
inUseWorkerCount integer — 当前已分配智能体的已连接 worker 数量。空闲容量为 connectedWorkerCount - inUseWorkerCount。
firstSeenAtMs, lastSeenAtMs integer — 首次和最后一次发现的时间，以 Unix 毫秒表示。
isStale boolean — 用量池是否因长期未活动而标记为过期。
repoOwner, repoName, repoUrl string (可选) — 用量池关联仓库时的仓库元数据。对于适用于任意仓库的用量池，这些字段会被省略。
workerReadyTimeoutSeconds integer — 已认领请求在认领过期前等待此用量池的离线 worker 重新连接的秒数。0 表示离线 worker 的后续请求会立即从用量池重新获取。

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 条目是适用于任意仓库的用量池：仓库字段会被省略，即使没有已连接的 worker，该用量池仍可供选择。

注册用量池

POST/v0/private-workers/pools

请求体

scope string (必填)

用量池归属范围。取值为 user 或 team。

poolName string (必填)

要注册的用量池名称 (例如 gpu) 。

repoOwner, repoName string (可选)

用量池关联仓库时的仓库元数据。请同时提供两者；适用于任意仓库的用量池则同时省略两者。

repoUrl string (可选)

用于显示的仓库 URL。需要提供 repoOwner 和 repoName。

workerReadyTimeoutSeconds integer (可选，默认值：0)

响应字段

registered boolean

用量池是否已注册。

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 string (必填)

用量池的归属范围。取值为 user 或 team。

pool_name string (必填)

要注销的用量池名称。

repo_owner string (可选)

注销仓库范围的用量池记录时的仓库所有者。

repo_name string (可选)

注销仓库范围的用量池记录时的仓库名称。请同时提供 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 的用量池，列表中还会显示已认领但离线的条目：即在重新连接窗口开启期间，所认领的 worker 处于离线状态的请求。这些条目会携带 claimedWorkerId 和 wakeTimeoutMs，以便 controller 能够唤醒该机器。

响应包含 streamCursor。将其传递给监视待处理用量池请求，即可在此快照之后实时跟踪队列变化。

查询参数

limit number (可选)

要返回的待处理请求数量。默认值：50；最大值：100。

pageToken string (可选)

上一响应返回的分页游标。页面 token 与生成它们时使用的 repository 和 pool 筛选条件绑定。

repository 字符串 (可选)

按仓库 URL 筛选。对于限定仓库范围的服务账户 API 密钥，此参数必填。若要获取任意仓库的待处理请求，则省略此参数。

pool 字符串 (可选)

按用量池名称筛选。与请求的 pool 标签进行精确的区分大小写匹配。省略则列出团队中所有用量池的请求。

响应字段

requests array

待处理请求。每个条目包括：

id string — 待处理请求 / 智能体 ID (作为 id 传递给认领或释放认领) 。
userId integer — 创建该请求的 Cursor 用户 ID。
userEmail string (可选) — 发起请求的用户的电子邮件 (如有)。可据此选择与用户关联的容量，无需额外查询。
serviceAccountId string (可选) — 与该请求关联的服务账户 (如有)。
repoOwner, repoName, repoUrl string (可选) — 请求以仓库为目标时的仓库元数据。任意仓库用量池请求中会省略。
labels array — 请求标签，以 { key, value } 键值对形式表示 (设置后会包含 repo= 和 pool=)。
createdAtMs integer — 请求创建时间，以 Unix 毫秒为单位。
claimedWorkerId string (可选) — 出现在已认领但离线的条目中：该请求已由此 worker 认领，但该 worker 当前离线。使用此 ID (CURSOR_AGENT_WORKER_ID) 启动 worker，以便在其机器上恢复智能体。
wakeTimeoutMs integer (可选) — 已认领但离线的条目在重新连接窗口内剩余的毫秒数。窗口到期后，认领将失效，该请求会作为未认领条目重新发布。

nextPageToken string (可选)

分页游标。没有更多页面时会省略。要衡量队列深度，请完成全部分页并统计请求数量。

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

响应：

{  "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) 流式传输待处理请求的生命周期事件，使控制器无需轮询即可响应队列更改。

查询参数

cursor string (必填)

repository 字符串 (可选)

语义与列出待处理用量池请求相同。对于仓库范围的服务账户 API 密钥，此项为必填。流不接受分页参数。

pool 字符串 (可选)

事件

监控会重放游标之后保留的状态转换，然后持续接收实时事件。每个事件的 SSE id: 都是连接中断后恢复时使用的游标。

created 事件 — 请求进入队列，包括已被认领但处于离线状态、重连窗口已过且认领已失效的请求。负载：与列出待处理用量池请求相同的请求对象。
claimed 事件 — worker 已认领该请求，或离线 worker 重新连接后恢复处理其已认领的请求。负载：{ id }。
claimed_offline 事件 — 已认领该请求的 worker 离线后收到后续消息。负载：与列出待处理用量池请求相同的请求对象，包括 claimedWorkerId 和 wakeTimeoutMs。在窗口到期前唤醒机器，否则认领将过期，并通过新的 created 事件重新发布该请求。
expired 事件 — 请求未被认领便离开队列。负载：{ id }。
heartbeat 事件 — 不含状态变化的游标检查点，在空闲流中约每 20 秒发送一次。负载：{}。心跳会推进空闲监控的恢复位置，但不会延长游标的生命周期。

游标生命周期

投递保证

不要持久化游标。一个服务账户最多可保持四个并发流；每个控制器使用一个流，并在本地扇出。

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

控制器循环：

列出所有待处理请求，并用结果更新本地视图。保留响应中的 streamCursor。
使用 ?cursor=<streamCursor> 建立 watch 连接，并将事件应用到本地视图。记录已处理的最新事件 id:。
断开连接后，使用最新事件 ID 作为 ?cursor= 重新连接；或者使用原生 EventSource，它会自动将其作为 Last-Event-ID 重新发送。
收到 HTTP 410 Gone 时，返回步骤 1，重新列出请求。

认领待处理请求

POST/v0/private-workers/claim

已存在有效认领时，第二次认领会被拒绝。请先释放认领，再认领新的 workerId。

此端点需要服务账户 API 密钥。

请求体

id string (必填)

待处理请求 ID。与列出待处理用量池请求返回的 id 值相同。

workerId string (必填)

为该请求预留的 worker ID。通过 CURSOR_AGENT_WORKER_ID (或隐藏的 --worker-id 标志) 使用相同 ID 启动 worker，以便 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"}

成功认领后，使用预留的 ID 启动 worker：

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

解除将智能体绑定到自托管 worker 的长期认领。释放后，Cursor 不再优先为该智能体选择该机器。

如果存在有效认领，第二次认领待处理请求将被拒绝。请先释放，再认领新的 workerId。

--idle-release-timeout (环境变量 CURSOR_WORKER_IDLE_RELEASE_TIMEOUT) 会使 worker CLI 在空闲后退出。此端点仅解除路由认领。

此端点需要服务账户 API 密钥。

路径参数

id string

待处理请求 / 智能体 ID。与认领待处理请求中的 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。

createdAt string

API 密钥的创建时间 (ISO 8601) 。

userId integer (用户级密钥)

API 密钥所有者的 Cursor 用户 ID (数字) 。对于 service-account / 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。Cursor 会依次解析你的用户默认模型、团队默认模型，最后回退到系统默认值。

响应字段

items 中的每一项描述一个模型：

id string

创建智能体时，将此值作为 model.id 传入。

displayName string

显示在 Cursor UI 中、便于阅读的名称。

description string (optional)

模型的简短描述。

aliases array (optional)

映射到同一模型的别名 ID (例如 composer-latest) 。

parameters array (optional)

variants array (optional)

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

列出已通过身份验证的用户可通过 Cursor 的 GitHub App 安装访问的 GitHub 仓库。

此端点的速率限制非常严格。

请将请求频率限制为 每用户每分钟 1 次，以及 每用户每小时 30 次。

对于可访问大量仓库的用户，此请求可能需要几十秒才能返回响应。

请确保在无法获取此信息时也能妥善处理。

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

响应：

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

Command Palette

API 概览

Cloud Agents API

管理 API

Analytics API

AI 代码追踪 API

源站 API

Cloud Agents API

Command Palette

API 概览

Cloud Agents API

管理 API

Analytics API

AI 代码追踪 API

源站 API

Cloud Agents API