Skip to main content
PUT /v1/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
X-CAS-Include-ExtendedNoSet to true to include extended fields (skills, metadata) in the response

​
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
instructionsstringNoSystem prompt
descriptionstringNoAgent description
toolsarrayNoTool configuration list
mcp_serversarrayNoMCP server configuration list
skillsarrayNoSkill bindings, format [{"type":"custom","skill_id":"<skill_id>"}], up to 20 entries
metadataobjectNoCustom metadata key-value pairs
default_environmentstringNoDefault runtime environment

​
Example request

curl -X PUT "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",
    "instructions": "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.",
  "instructions": "You are an updated documentation testing assistant.",
  "tools": [],
  "mcp_servers": [],
  "default_environment": "",
  "version": 2,
  "archived": false,
  "archived_at": null,
  "created_at": "2026-05-18T15:26:39.61669Z",
  "updated_at": "2026-05-18T15:27:07.967138Z"
}

​
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_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",
  "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.
  • View the change history with GET /v1/agents/{agent_id}/versions.