Documentation Index
Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
Use this file to discover all available pages before exploring further.
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.
| 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 |
system | string | No | System prompt |
description | string | No | Agent description |
tools | array | No | Tool configuration list |
mcp_servers | array | No | MCP server configuration list |
metadata | object | No | Custom metadata key-value pairs |
default_environment | string | No | Default runtime environment |
Example request
curl -X PUT "https://openapi.qoder.sh/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.",
"instructions": "You are an updated documentation testing assistant.",
"tools": [],
"mcp_servers": [],
"default_environment": "",
"version": 2,
"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:
- The client first calls
GET to obtain the current version.
- The update sends that
version in the request body.
- The server checks whether the supplied
version matches the current value.
- On match, the update succeeds and
version increments by 1.
- 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 |
| 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) |
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 replace semantics: optional fields not included are reset to empty. Pass all current field values when updating.
- View the change history with
GET /v1/agents/{agent_id}/versions.
