Update an agent - Qoder CN

Update the configuration of an existing agent. Uses optimistic concurrency control (OCC); the current version must be supplied in the request body. POST /api/v1/cloud/agents/{agent_id}

Request headers

Header	Required	Description
`Authorization`	Yes	`Bearer <PAT>`
`Content-Type`	Yes	`application/json`

Path parameters

Parameter	Type	Required	Description
`agent_id`	string	Yes	Unique agent identifier.

Request body

Field	Type	Required	Description
`version`	integer	Yes	Current version number for OCC. Must match the server-side value.
`name`	string	No	Agent name, 1-256 characters.
`model`	string\|object	No	Model identifier. Pass a string, or an Agent model object to also set `effort` or `context_window`. Query the available values with List models.
`system`	string	No	System prompt, up to 100000 characters.
`description`	string	No	Agent description, up to 2048 characters.
`tools`	array	No	Replaces the saved tool configuration list. Up to 128 entries.
`mcp_servers`	array	No	Replaces the saved MCP server list. Up to 20 entries. Any `mcp_toolset` in `tools` must reference a name in this list.
`skills`	array	No	Replaces the saved Skill binding list. Up to 20 entries.
`metadata`	object	No	Metadata patch. A string value adds or updates a key; a `null` value removes a key from the saved metadata.

Example request

curl -X POST "https://api.qoder.com.cn/api/v1/cloud/agents/agent_019eXXXX..." \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "doc-test-agent-updated",
    "model": "ultimate",
    "system": "You are the updated documentation test assistant.",
    "description": "Used for API documentation testing.",
    "version": 1
  }'

Example response

HTTP 200 OK

{
  "type": "agent",
  "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "name": "doc-test-agent-updated",
  "description": "Used for API documentation testing.",
  "model": "ultimate",
  "system": "You are the updated documentation test assistant.",
  "tools": [],
  "mcp_servers": [],
  "skills": [],
  "metadata": {},
  "multiagent": null,
  "version": 2,
  "archived_at": null,
  "created_at": "2026-05-18T15:26:39.61669Z",
  "updated_at": "2026-05-18T15:27:07.967138Z"
}

Response fields

Field	Type	Description
`type`	string	Always `"agent"`.
`id`	string	Unique agent identifier, prefixed with `agent_`.
`name`	string	Agent name.
`description`	string	Agent description.
`model`	string\|object	Model identifier.
`system`	string	System prompt.
`tools`	array	Tool configuration list.
`mcp_servers`	array	MCP server configuration.
`skills`	array	Skill binding list.
`metadata`	object	Custom metadata.
`multiagent`	object\|null	Agents configuration, or `null` when not set.
`version`	integer	New version number after the update.
`archived_at`	string\|null	Archive time (ISO 8601), or `null` when not archived.
`created_at`	string	Creation time (ISO 8601).
`updated_at`	string	Last update time (ISO 8601).

Optimistic concurrency control (OCC)

Update requests use the version number for optimistic locking:

The client first calls GET to obtain the agent's current version.
The client sends the update with that version in the request body.
The server verifies that version matches the current server-side value.
If they match, the update succeeds and version is incremented by 1.
If they do not match, the server returns 409 Conflict.

This prevents concurrent clients from overwriting each other's changes to the same agent.

Errors

HTTP	Type	Trigger
400	`invalid_request_error`	Request body or field value is invalid.
400	`invalid_request_error`	`model.effort` is not one of `none`, `low`, `medium`, `high`, `xhigh`, `max`.
400	`invalid_request_error`	`model.context_window` is not a positive integer.
400	`invalid_request_error`	`model.speed` was provided; use `model.effort` instead.
400	`invalid_request_error`	`tools` exceeds the maximum of 128 entries.
400	`invalid_request_error`	`mcp_servers` exceeds the maximum of 20 entries.
400	`invalid_request_error`	`skills` exceeds the maximum of 20 entries.
401	`authentication_error`	PAT is invalid or has expired.
403	`permission_error`	Caller is not authorized to update this agent.
404	`not_found_error`	No agent exists with the given ID.
409	`conflict_error`	`version` does not match: concurrent modification.

Version conflict (409) response example:

{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "conflict_error",
    "message": "Version conflict. Expected version 99, got 1."
  }
}

For the full error envelope, see Errors.

Notes

version is required; omitting it causes the update to fail.
version is incremented on every successful update.
Updates use partial-update (merge) semantics: optional fields not present in the request body keep their previous values, and only explicitly provided fields are updated.
When tools, mcp_servers, or skills is provided explicitly, that field's array is replaced in full by the array in the request.
When metadata is provided explicitly, string values are merged into the saved metadata object, and null values remove existing keys.
Use List Agent versions to view historical versions.

​Request headers

​Path parameters

​Request body

​Example request

​Example response

​Response fields

​Optimistic concurrency control (OCC)

​Errors

​Notes