> ## 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. # Create an agent > Create a new Agent configuration. `POST /api/v1/cloud/agents` Creates a new Agent configuration. ## Headers | Header | Required | Description | | ----------------- | -------- | --------------------------------------------- | | `Authorization` | Yes | `Bearer ` | | `Content-Type` | Yes | `application/json` | | `Idempotency-Key` | No | Idempotency key to prevent duplicate creation | ## Request body | Field | Type | Required | Description | | ------------- | ------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `name` | string | Yes | Agent name, 1-256 characters | | `model` | string \| object | Yes | Model identifier. Pass a string such as `"ultimate"`, or an [Agent model](/cloud-agents/api/agents/schemas#agent-model) object to configure `effort` or `context_window` alongside the model ID. Use [List models](/cloud-agents/api/models/list) 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](/cloud-agents/api/agents/schemas#agent-tool) | No | Tool configuration list, up to 128 entries | | `mcp_servers` | array of [MCP server](/cloud-agents/api/agents/schemas#mcp-server) | No | MCP server configuration list, up to 20 entries. Authentication is configured through [Vaults](/cloud-agents/vaults). | | `skills` | array of [Skill binding](/cloud-agents/api/agents/schemas#skill-binding) | No | Skill bindings, up to 20 entries | | `metadata` | [Metadata object](/cloud-agents/api/conventions/schemas#metadata-object) | No | Custom metadata. Defaults to `{}` | | `multiagent` | [Multiagent](/cloud-agents/api/agents/schemas#multiagent) | No | Agents configuration. When set, requires an `agent_toolset_20260401` tool entry | ## Example request ```bash theme={null} curl -X POST "https://api.qoder.com/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.", "tools": [ { "type": "agent_toolset_20260401", "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"] } ], "mcp_servers": [ { "type": "url", "name": "weather-service", "url": "https://mcp.example.com/mcp" } ] }' ``` To configure reasoning effort or the context window, pass `model` as an object: ```bash theme={null} curl -X POST "https://api.qoder.com/api/v1/cloud/agents" \ -H "Authorization: Bearer $QODER_PAT" \ -H "Content-Type: application/json" \ -d '{ "name": "doc-test-agent-tuned", "model": { "id": "ultimate", "effort": "high", "context_window": 400000 }, "system": "You are a documentation testing assistant." }' ``` ## Example response **HTTP 200 OK** ```json theme={null} { "type": "agent", "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "name": "doc-test-agent", "description": "", "model": "ultimate", "system": "You are a documentation testing assistant.", "tools": [ { "type": "agent_toolset_20260401", "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"] } ], "mcp_servers": [ { "type": "url", "name": "weather-service", "url": "https://mcp.example.com/mcp" } ], "skills": [], "metadata": {}, "multiagent": null, "version": 1, "archived_at": null, "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 \| object | Model identifier. See [Agent model](/cloud-agents/api/agents/schemas#agent-model) | | `system` | string | System prompt | | `tools` | array of [Agent tool](/cloud-agents/api/agents/schemas#agent-tool) | Tool configuration list | | `mcp_servers` | array of [MCP server](/cloud-agents/api/agents/schemas#mcp-server) | MCP server configuration | | `skills` | array of [Skill binding](/cloud-agents/api/agents/schemas#skill-binding) | Skill bindings | | `metadata` | [Metadata object](/cloud-agents/api/conventions/schemas#metadata-object) | Custom metadata | | `multiagent` | [Multiagent](/cloud-agents/api/agents/schemas#multiagent) \| null | Agents configuration, `null` when not set | | `version` | integer | Current version, starting at 1 | | `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) | ## 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` | `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` | Invalid `mcp_servers` or `skills` configuration | | 400 | `invalid_request_error` | `skills` exceeds the maximum of 20 entries | | 400 | `invalid_request_error` | `multiagent.type` is not `"coordinator"` | | 400 | `invalid_request_error` | `multiagent.agents` is empty or exceeds the maximum of 20 entries | | 400 | `invalid_request_error` | `multiagent` is set but `tools` is missing an `agent_toolset_20260401` entry | | 400 | `invalid_request_error` | Agent ID referenced in `multiagent.agents` does not exist | | 401 | `authentication_error` | PAT invalid or expired | | 403 | `permission_error` | Not authorized for this operation | See [Errors](/cloud-agents/api/conventions/errors) for the full error envelope. ### Error response example ```json theme={null} { "type": "error", "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14", "error": { "type": "invalid_request_error", "message": "name must be between 1 and 256 characters" } } ``` ## Related Create a reusable, versioned agent configuration.