Skip to main content
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

HeaderRequiredDescription
AuthorizationYesBearer <PAT>
Content-TypeYesapplication/json

​
Path parameters

ParameterTypeRequiredDescription
agent_idstringYesAgent unique identifier

​
Request body

FieldTypeRequiredDescription
versionintegerYesCurrent version (OCC). Must match the server-side version.
namestringNoAgent name, 1-256 characters
modelstring | objectNoModel identifier. Pass a string or an Agent model object to configure effort or context_window. Use List models to discover available values
systemstringNoSystem prompt, at most 100000 characters
descriptionstringNoAgent description, at most 2048 characters
toolsarray of Agent toolNoReplaces the stored tool configuration list. Maximum 128 entries
mcp_serversarray of MCP serverNoReplaces the stored MCP server list. Maximum 20 entries. mcp_toolset entries in tools must reference names in this list
skillsarray of Skill bindingNoReplaces the stored skill binding list. Maximum 20 entries
metadataobjectNoMetadata 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

FieldTypeDescription
typestringAlways "agent"
idstringAgent unique identifier with the agent_ prefix
namestringAgent name
descriptionstringAgent description
modelstring | objectModel identifier. See Agent model
systemstringSystem prompt
toolsarray of Agent toolTool configuration list
mcp_serversarray of MCP serverMCP server configuration
skillsarray of Skill bindingSkill bindings
metadataMetadata objectCustom metadata
multiagentMultiagent | nullAgents configuration, null when not set
versionintegerNew version after the update
archived_atstring|nullArchive time (ISO 8601), null when not archived
created_atstringCreation time (ISO 8601)
updated_atstringLast 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

HTTPTypeTrigger
400invalid_request_errorMalformed body or invalid field value
400invalid_request_errormodel.effort is not one of none, low, medium, high, xhigh, max
400invalid_request_errormodel.context_window is not a positive integer
400invalid_request_errormodel.speed was supplied; use model.effort instead
400invalid_request_errortools exceeds the maximum of 128 entries
400invalid_request_errormcp_servers exceeds the maximum of 20 entries
400invalid_request_errorskills exceeds the maximum of 20 entries
401authentication_errorPAT invalid or expired
403permission_errorNot authorized to update this Agent
404not_found_errorAgent with the given ID does not exist
409conflict_errorversion 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.

Agent setup

Create a reusable, versioned agent configuration.