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.
POST /v1/agents
Creates a new Agent configuration.
| Header | Required | Description |
|---|
Authorization | Yes | Bearer <PAT> |
Content-Type | Yes | application/json |
Idempotency-Key | No | Idempotency key to prevent duplicate creation. See Idempotency. |
Request body
| Field | Type | Required | Description |
|---|
name | string | Yes | Agent name, 1–256 characters |
model | string/object | Yes | Model identifier; either a string (such as "ultimate") or an object |
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 |
Example request
curl -X POST "https://openapi.qoder.sh/api/v1/cloud/agents" \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"name": "doc-test-agent",
"model": "ultimate",
"system": "You are a documentation testing assistant."
}'
Example response
HTTP 201 Created
{
"type": "agent",
"id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"name": "doc-test-agent",
"description": "",
"model": "ultimate",
"system": "You are a documentation testing assistant.",
"instructions": "You are a documentation testing assistant.",
"tools": [],
"mcp_servers": [],
"default_environment": "",
"version": 1,
"created_at": "2026-05-18T15:26:39.61669Z",
"updated_at": "2026-05-18T15:26:39.61669Z"
}
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 | Model identifier |
system | string | System prompt |
instructions | string | Instruction content (kept in sync with system) |
tools | array | Tool configuration list |
mcp_servers | array | MCP server configuration |
default_environment | string | Default runtime environment |
version | integer | Current version, starting at 1 |
created_at | string | Creation time (ISO 8601) |
updated_at | string | Last update time (ISO 8601) |
Errors
| HTTP | Type | Trigger |
|---|
| 400 | invalid_request_error | Missing required field name |
| 400 | invalid_request_error | name exceeds 256 characters |
| 400 | invalid_request_error | Missing required field model |
| 400 | invalid_request_error | Invalid mcp_servers or skills configuration |
| 401 | authentication_error | PAT invalid or expired |
| 403 | permission_error | Not authorized for this operation |
Error response example
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "name must be between 1 and 256 characters"
}
}
