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