API 參考

API 參考總覽

每個端點的參數、請求本文與回應都由程式裡實際驗證請求的定義產生，與線上行為一致。

兩個 API

OpenAPI 3.1（JSON），可以匯入你慣用的 API 工具或用來產生用戶端程式碼：

文件裡的擴充欄位：x-scope（Agent 金鑰需要的範圍）、x-roles（個人金鑰可用的角色）、x-mcp-tool（做同一件事的 MCP 工具）、x-idempotent（可帶 Idempotency-Key）。

錯誤一律是 { "error": { "code", "message", "request_id" } }。

HTTP	code	意思
400	invalid_request	參數格式不對（message 會指出哪個欄位）
401	unauthorized	沒帶金鑰、格式錯、不存在或已撤銷
403	forbidden	金鑰的角色沒有這個範圍，或不是你負責的帳號／稿
404	not_found	找不到（包含不屬於你的）
409	ambiguous_code	舊編號在多個平台重複，請加 platform
409	idempotency_in_progress	同一個 Idempotency-Key 的第一個請求還在處理
413	payload_too_large	內容或圖片太大
422	rejected	規則不允許（message 是原因）
422	idempotency_mismatch	同一個 Idempotency-Key 用在不同內容
429	rate_limited	超過每把金鑰每分鐘的上限，看 Retry-After
500	internal	伺服器錯誤，可用同一個 Idempotency-Key 重試

HTTP	code	意思
400	invalid_request	參數格式不對（message 會指出哪個欄位）
401	unauthorized	沒帶金鑰、金鑰錯誤或已撤銷、Agent 金鑰的工作區已封存、還沒完成首次登入設定、已不是組織成員
403	forbidden	你的角色不能做這件事
404	not_found	找不到，或你看不到（不會說是哪一種）
413	payload_too_large	請求內容太大
422	rejected	規則不允許（message 是原因）
429	rate_limited	太快了，看 Retry-After 秒數再試
500	internal	伺服器錯誤