Agent Test API (Update / Release)
Agent Test API (Update / Release)
Allows developers to use AI tools such as CodeX and Claude (with the GPTBots Agent Skill installed) to import the .bot file configuration generated by Skills into a target Agent on the GPTBots platform and release it to production.
⚠️ Only Agents in "test mode" can be called. Calling an Agent in production mode returns
403200. Test mode is selected when creating an Agent and cannot be changed after creation.
Agent Update API (Import .bot to replace the current version)
Imports the .bot file into the target Agent (test mode), and saves the replaced current configuration as a new draft version (which also becomes the "current version"). The specific rules are as follows:
- Knowledge bases (data groups) / database tables / knowledge documents: scoped by AgentID; those still belonging to the target Agent are retained, otherwise discarded;
- Linked workflows / tools (plugins): scoped by organization; those still valid are retained, otherwise discarded;
- Top-level knowledge base mounts are not exported with the
.bot; on import, the knowledge bases already mounted on the target Agent itself are retained; - Third-party credentials: when importing into an existing Agent, credentials already configured on the target are backfilled by "identical component/node/plugin ID", without clearing already-authenticated components, to ensure availability;
Request Method
POST
Request URL
https://api-${endpoint}.gptbots.ai/v1/agent/version/import
Request
Request Example
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'
This code block in the floating window
Request Headers
| Field | Type | Description |
|---|---|---|
| Authorization | Bearer {API Key} | Use Authorization: Bearer {API Key} for authentication. Get the key from the target Agent's "Integration / API" channel as the API Key. |
| Content-Type | multipart/form-data | Data type, set to multipart/form-data. |
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| file | file | Yes | Binary .bot file. |
| versionDesc | text | No | Version description. |
The version number is generated automatically by the server (the last segment of the latest version +1; if there is no version history, it is
1.0.0).
Response
Response Example
{
"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"
}
}
This code block in the floating window
Success Response
| Field | Type | Description |
|---|---|---|
| botId | string | Target Agent ID. |
| botType | string | Agent type (QuestionAnswer / Flow / LoopAgent). |
| version | string | The version number saved this time (i.e. the current version). |
Failure Response
| Field | Type | Description |
|---|---|---|
| code | int | Error code. |
| msg | string | Error details. |
Agent Release API (Release a version number to production)
Releases the specified version number of the target Agent (test mode) as the live production version (that version becomes "live", and the other versions revert to draft state).
Request Method
POST
Request URL
https://api-${endpoint}.gptbots.ai/v1/agent/version/release
Request
Request Example
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"
}'
This code block in the floating window
Request Headers
| Field | Type | Description |
|---|---|---|
| Authorization | Bearer {API Key} | Use Authorization: Bearer {API Key} for authentication. Get the key from the target Agent's "Integration / API" channel as the API Key. |
| Content-Type | application/json | Data type, set to application/json. |
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| version | string | Yes | The version number to release as live (e.g. 1.0.3), usually the version returned by the "Update" API. |
Response
Response Example
{
"code": 0,
"msg": "OK"
}
{
"code": 0,
"msg": "OK"
}
This code block in the floating window
Success Response
No data body; a code of 0 means the release succeeded.
Failure Response
| Field | Type | Description |
|---|---|---|
| code | int | Error code. |
| msg | string | Error details. |
Error Codes
The Update and Release APIs share the same set of error codes:
| Code | Message |
|---|---|
| 0 | Success |
| 20055 | The Agent's API channel is not enabled. Turn on the API switch under Integration / API first |
| 40000 | Invalid parameter. The Release API was called without version; or the imported LoopAgent Loop Control values are invalid (maxTurns must be 1–100, maxErrors 0–50, maxBudgetInputTokens ≥ 0, and all must be integers) |
| 40001 | Too many requests: this API is limited to 30 requests per minute per Agent |
| 40008 | Too many requests: the plan's RPM limit for Other APIs was exceeded (not triggered if the plan does not set this limit) |
| 40101 | The Authorization header is empty |
| 40127 | Developer authentication failed: invalid API Key |
| 40348 | Agent does not exist. Returned only if the Agent is deleted concurrently after authentication; an invalid API Key returns 40127 and a deleted Agent returns 40378 |
| 40353 | The feature is only available after upgrading the plan. Release API: the published count has reached the plan limit (the response carries this generic message and does not include the limit) |
| 40355 | Flow rule invalid. Release API: the target is a Flow-Agent whose flow graph is invalid |
| 40378 | Agent deleted |
| 200268 | Agent/Workflow version already exists: the auto-derived version number collides with an existing version (the HTTP status for this code is 200) |
| 403200 | Not in test mode: only Agents in test mode can be updated or released by this API |
| 403201 | The imported file type does not match the target Agent type |
| 403202 | Failed to parse the imported .bot file |
| 403203 | The specified version number does not exist |
| 403204 | API Key type does not match the API: this API only accepts an Agent Key |