Update an agent

Update an Agent configuration with optimistic concurrency control.

POST /api/v1/cloud/agents/{agent_id}

Updates the configuration of the specified Agent. Uses optimistic concurrency control (OCC); the request body must include the current version.

Headers

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

Path parameters

Parameter	Type	Required	Description
agent_id	string	Yes	Agent unique identifier

Request body

Field	Type	Required	Description
version	integer	Yes	Current version (OCC). Must match the server-side version.
name	string	No	Agent name, 1-256 characters
model	string | object	No	Model identifier. Pass a string or an Agent model object to configure effort or context_window. Use List models to discover available values
system	string	No	System prompt, at most 100000 characters
description	string	No	Agent description, at most 2048 characters
tools	array of Agent tool	No	Replaces the stored tool configuration list. Maximum 128 entries
mcp_servers	array of MCP server	No	Replaces the stored MCP server list. Maximum 20 entries. mcp_toolset entries in tools must reference names in this list
skills	array of Skill binding	No	Replaces the stored skill binding list. Maximum 20 entries
metadata	object	No	Metadata patch. String values upsert keys; null values delete keys from stored metadata

Example request

curl -X POST "https://api.qoder.com/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 an updated documentation testing 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 an updated documentation testing 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	Agent unique identifier with the agent_ prefix
name	string	Agent name
description	string	Agent description
model	string | object	Model identifier. See Agent model
system	string	System prompt
tools	array of Agent tool	Tool configuration list
mcp_servers	array of MCP server	MCP server configuration
skills	array of Skill binding	Skill bindings
metadata	Metadata object	Custom metadata
multiagent	Multiagent | null	Agents configuration, null when not set
version	integer	New version after the update
archived_at	string|null	Archive time (ISO 8601), null when not archived
created_at	string	Creation time (ISO 8601)
updated_at	string	Last update time (ISO 8601)

Optimistic concurrency control (OCC)

Updates use the version number for optimistic locking:

1. The client first calls GET to obtain the current version.
2. The update sends that version in the request body.
3. The server checks whether the supplied version matches the current value.
4. On match, the update succeeds and version increments by 1.
5. On mismatch, the server returns 409 Conflict.

This prevents concurrent updates from overwriting each other.

Errors

HTTP	Type	Trigger
400	invalid_request_error	Malformed body or invalid field value
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 supplied; 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 invalid or expired
403	permission_error	Not authorized to update this Agent
404	not_found_error	Agent with the given ID does not exist
409	conflict_error	version mismatch (concurrent modification)

See Errors for the full error envelope.

Error response example

Version conflict (409):

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

Notes

• version is required; omitting it causes the update to fail.
• version increments on each successful update.
• Updates use merge semantics: optional fields not included in the request body retain their current values. Only explicitly provided fields are updated.
• When tools, mcp_servers, or skills is provided, the supplied array replaces the stored array for that field.
• When metadata is provided, string values are merged into the stored metadata object and null values delete existing keys.
• View the change history with GET /api/v1/cloud/agents/{agent_id}/versions.

Related

Agent setup

Create a reusable, versioned agent configuration.