跳轉到

API 參考文件

本章節提供 Codeer API 的完整文件，讓你能夠建立與 AI Agent 的自訂整合。

基礎 URL

所有 API 請求應發送至：

https://api.codeer.ai/api/v1

認證

所有 API 請求都需要使用 API 金鑰進行認證。在請求標頭中加入你的 API 金鑰：

x-api-key: YOUR_API_KEY

關於如何取得 API 金鑰，請參閱 API 存取設定。

回應格式

所有 API 回應遵循標準的封裝格式：

{
  "data": { ... },
  "message": null,
  "error_code": 0,
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total_records": 100,
    "total_pages": 2,
    "current_page": 1,
    "next_page": "https://api.codeer.ai/api/v1/chats?offset=50&limit=50",
    "prev_page": null
  }
}
欄位 說明
data 回應資料（物件、陣列或 null）
message 人類可讀的狀態訊息（成功時為 null，錯誤時為錯誤說明）
error_code 錯誤代碼，為整數（成功時為 0）
pagination 分頁資訊（僅適用於列表端點）

可用端點

Chat API

方法 端點 說明
GET /chats/published-agents 列出已發布的 Agent
POST /chats 建立新的聊天會話
GET /chats 列出聊天會話
GET /chats/{chat_id}/messages 取得聊天中的訊息
POST /chats/{chat_id}/messages 發送訊息（支援 SSE 串流）
POST /chats/upload-file 上傳檔案附件
POST /chats/{chat_id}/messages/{message_id}/feedbacks 提交訊息回饋

詳細文件請參閱 Chat API。

Batch API

方法 端點 說明
POST /batches 建立批次請求
GET /batches 列出批次
GET /batches/{batch_id} 取得批次狀態
GET /batches/{batch_id}/results 取得批次結果
POST /batches/{batch_id}/cancel 取消批次

詳細文件請參閱 Batch API。

錯誤代碼

當發生錯誤時，回應會包含 error_code 欄位（整數）：

HTTP 狀態碼 錯誤代碼 名稱 說明
400 10001 SYS_PERMISSION_DENIED 無效或缺少 API 金鑰
400 10006 SYS_BAD_REQUEST 無效的請求參數
403 10001 SYS_PERMISSION_DENIED 存取被拒絕
403 14103 WORKSPACE_CLIENT_NOT_ALLOWED 用戶不在白名單中（請參閱下方說明）
404 10003 SYS_NOT_FOUND 找不到資源
500 10005 SYS_SERVER_ERROR 內部伺服器錯誤

白名單模式與 external_user_id

當工作空間啟用白名單模式時，external_user_id 參數實際上變成必填。沒有有效白名單 external_user_id 的請求將收到錯誤代碼 14103 的 403 回應。

速率限制

API 請求受到速率限制。如果超過限制，你會收到 429 Too Many Requests 回應。

處理速率限制

  • 在你的用戶端實作帶有抖動的指數退避
  • 從 1 秒延遲開始，每次重試加倍（1秒、2秒、4秒、8秒...）
  • 加入隨機抖動（±10-25%）以防止驚群效應
  • 設定最大重試次數（例如：5 次）或最大延遲（例如：32 秒）

下一步