代理測試 API（更新/發布）
代理測試 API（更新/發布）
支援開發者在 CodeX、Claude 等 AI 工具（已安裝 GPTBots Agent Skill）把 Skills 生成的 .bot 檔案配置匯入到一個 GPTBots 平台目標 代理 並發布上線。
⚠️ 僅「測試模式」的代理可被呼叫。 正式模式呼叫回傳
403200。測試模式在建立代理時選擇，建立後不可修改。
代理更新 API（匯入 .bot 替換目前版本）
把 .bot 檔案匯入到目標代理（測試模式），將替換後的目前配置儲存為一個新的草稿版本（同時成為「目前版本」）。具體規則如下：
- 知識庫（資料組）/ 資料庫表 / 知識文件：按 AgentID 維度，仍屬於目標代理的保留、否則丟棄；
- 關聯 workflow / 工具（外掛）：按 組織 維度，仍有效的保留、否則丟棄；
- 頂層知識庫掛載不隨
.bot匯出，匯入時保留目標代理自身已掛載的知識庫； - 第三方憑證：匯入到現有代理時按「相同元件/節點/外掛 ID」回填目標已配置的憑證，不清空已鑑權元件，保證可用性；
請求方式
POST
呼叫位址
https://api-${endpoint}.gptbots.ai/v1/agent/version/import
請求
請求範例
curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/agent/version/import' \
-H 'Authorization: Bearer {AGENT_API_KEY}' \
-H 'Content-Type: multipart/form-data' \
-F 'file=@my-agent.bot' \
-F 'versionDesc=Imported by AI tool'
curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/agent/version/import' \
-H 'Authorization: Bearer {AGENT_API_KEY}' \
-H 'Content-Type: multipart/form-data' \
-F 'file=@my-agent.bot' \
-F 'versionDesc=Imported by AI tool'
此代碼塊在浮窗中顯示
請求標頭
| 欄位 | 類型 | 描述 |
|---|---|---|
| Authorization | Bearer {API Key} | 使用 Authorization: Bearer {API Key} 進行呼叫驗證，請在目標代理的「整合 / API」渠道取得金鑰作為 API Key。 |
| Content-Type | multipart/form-data | 資料類型，取值為 multipart/form-data。 |
請求參數
| 欄位 | 類型 | 必填 | 描述 |
|---|---|---|---|
| file | file | 是 | 二進位 .bot 檔案。 |
| versionDesc | text | 否 | 版本說明。 |
版本號由伺服端自動生成（取最新版本末段 +1，無歷史版本則為
1.0.0）。
回應
回應範例
{
"code": 0,
"msg": "OK",
"data": {
"botId": "xxx",
"botType": "QuestionAnswer",
"version": "1.0.3"
}
}
{
"code": 0,
"msg": "OK",
"data": {
"botId": "xxx",
"botType": "QuestionAnswer",
"version": "1.0.3"
}
}
此代碼塊在浮窗中顯示
成功回應
| 欄位 | 類型 | 描述 |
|---|---|---|
| botId | string | 目標代理 ID。 |
| botType | string | 代理類型（QuestionAnswer / Flow / LoopAgent）。 |
| version | string | 本次儲存的版本號（即目前版本）。 |
失敗回應
| 欄位 | 類型 | 描述 |
|---|---|---|
| code | int | 錯誤碼。 |
| msg | string | 錯誤詳情。 |
代理發布 API（按版本號發布為線上版本）
將目標代理（測試模式）的指定版本號發布為線上生產版本（該版本變為「線上」，其餘版本回到草稿狀態）。
請求方式
POST
呼叫位址
https://api-${endpoint}.gptbots.ai/v1/agent/version/release
請求
請求範例
curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/agent/version/release' \
-H 'Authorization: Bearer {AGENT_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"version": "1.0.3"
}'
curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/agent/version/release' \
-H 'Authorization: Bearer {AGENT_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"version": "1.0.3"
}'
此代碼塊在浮窗中顯示
請求標頭
| 欄位 | 類型 | 描述 |
|---|---|---|
| Authorization | Bearer {API Key} | 使用 Authorization: Bearer {API Key} 進行呼叫驗證，請在目標代理的「整合 / API」渠道取得金鑰作為 API Key。 |
| Content-Type | application/json | 資料類型，取值為 application/json。 |
請求參數
| 欄位 | 類型 | 必填 | 描述 |
|---|---|---|---|
| version | string | 是 | 要發布為線上的版本號（如 1.0.3），通常取「更新」介面回傳的 version。 |
回應
回應範例
{
"code": 0,
"msg": "OK"
}
{
"code": 0,
"msg": "OK"
}
此代碼塊在浮窗中顯示
成功回應
無資料體，code 為 0 即發布成功。
失敗回應
| 欄位 | 類型 | 描述 |
|---|---|---|
| code | int | 錯誤碼。 |
| msg | string | 錯誤詳情。 |
錯誤碼
更新與發布介面共用同一套錯誤碼：
| Code | Message |
|---|---|
| 0 | 成功 |
| 20055 | 該代理未開啟 API 管道，請先在「整合 / API」中打開 API 開關 |
| 40000 | 參數錯誤。發布介面未傳 version；或匯入的 LoopAgent Loop Control 取值不合法（maxTurns 需在 1–100，maxErrors 需在 0–50，maxBudgetInputTokens 需 ≥ 0，且均須為整數） |
| 40001 | 請求過於頻繁：本介面依代理維度限流 30 次/分鐘 |
| 40008 | 請求過於頻繁：超出方案「其他 API」的 RPM 限制（方案未設定該項時不會觸發） |
| 40101 | 請求標頭 Authorization 為空 |
| 40127 | 開發者鑑權失敗：API Key 無效 |
| 40348 | 代理不存在。僅在鑑權通過後代理被並行刪除時出現；API Key 無效回傳 40127，代理已刪除回傳 40378 |
| 40353 | 升級方案後才支援使用該功能。發布介面：已發布數量達到方案上限（回應文案為該通用提示，不含具體數量） |
| 40355 | Flow 流程不符合規則。發布介面：目標為 Flow-Agent 且其流程圖不合法 |
| 40378 | 代理已刪除 |
| 200268 | Agent/Workflow 版本號已存在，不能重複：伺服器自動推導的版本號與既有版本衝突（該錯誤碼的 HTTP 狀態為 200） |
| 403200 | 非測試模式：僅測試模式的代理可被該 API 更新或發布 |
| 403201 | 匯入檔案類型與目標代理類型不符 |
| 403202 | 匯入的 .bot 檔案解析失敗 |
| 403203 | 指定的版本號不存在 |
| 403204 | API Key 類型與介面不符：本介面只接受 Agent Key |