《Cursor文档》-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 参考仍可用。

端点¶

创建代理¶

/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¶

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

获取智能体¶

/v1/agents/

获取智能体的持久元数据。执行状态存储在运行中——获取 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"
}

创建运行¶

/v1/agents//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"
  }
}

列出运行¶

/v1/agents//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"
          }
        ]
      }
    }
  ]
}

获取某次运行¶

/v1/agents//runs/

获取特定运行的状态、时间戳，以及 (对于已结束的运行) 最终结果、持续时间和已推送的分支。

路径参数¶

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

流式传输某次运行¶

/v1/agents//runs//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: status
data: {"runId":"run-00000000-0000-0000-0000-000000000001","status":"RUNNING"}

id: 1713033000000-0
event: assistant
data: {"text":"I'll update the README now."}

id: 1713033005000-0
event: tool_call
data: {"callId":"call-1","name":"read_file","status":"running","args":{"path":"README.md"}}

id: 1713033006000-0
event: tool_call
data: {"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-0
event: result
data: {"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-0
event: done
data: {}

取消运行¶

/v1/agents//runs//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"
}

获取智能体用量¶

/v1/agents//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
      }
    }
  ]
}

产物¶

产物归属于特定智能体，因为工作区会在多次运行之间持续保留。

列出产物¶

/v1/agents//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"
    }
  ]
}

下载产物¶

/v1/agents//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"
}

智能体生命周期¶

归档智能体¶

/v1/agents//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"
}

取消归档智能体¶

/v1/agents//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"
}

永久删除智能体¶

/v1/agents/

永久删除智能体。此操作不可逆。如需可撤销的移除方式，请使用归档。

路径参数¶

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¶

/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 断开连接后保持注册，因此您可以缩减至零，并在出现待处理请求时恢复容量。

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

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

列出 worker¶

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

获取机群摘要¶

/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¶

/v0/private-workers/

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

路径参数¶

id string

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

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

列出用量池¶

/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 (可选) — 用量池关联仓库时的仓库元数据。对于任意仓库用量池，这些字段会被省略。
offlineReconnectTimeoutSeconds 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,
      "offlineReconnectTimeoutSeconds": 900
    },
    {
      "scope": "team",
      "ownerId": 456,
      "poolName": "sandbox",
      "connectedWorkerCount": 0,
      "inUseWorkerCount": 0,
      "firstSeenAtMs": 1737100000000,
      "lastSeenAtMs": 1737200000000,
      "isStale": false,
      "offlineReconnectTimeoutSeconds": 0
    }
  ]
}

sandbox 条目适用于任意仓库：仓库字段会被省略，即使没有已连接的 worker，该用量池仍可供选择。

注册用量池¶

/v0/private-workers/pools

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

请求体¶

scope string (必填)

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

poolName string (必填)

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

repoOwner, repoName string (可选)

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

repoUrl string (可选)

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

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

注销用量池¶

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

列出待处理用量池请求¶

/v0/private-workers/pending-requests

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

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

此端点需要服务账户 API 密钥。它返回该密钥所属团队的请求，不包含我的机器请求。如果密钥仅限用于特定仓库，请传入 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 会省略其中的嵌入式凭据。

监控待处理用量池请求¶

/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，重新列出请求。

认领待处理请求¶

/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

释放认领¶

/v0/private-workers/claims//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 密钥信息¶

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

列出模型¶

/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 仓库¶

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