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 <PAT>
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 object to configure effort or context_window alongside the model ID. Use List models 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	No	Tool configuration list, up to 128 entries
mcp_servers	array of MCP server	No	MCP server configuration list, up to 20 entries. Authentication is configured through Vaults.
skills	array of Skill binding	No	Skill bindings, up to 20 entries
metadata	Metadata object	No	Custom metadata. Defaults to {}
multiagent	Multiagent	No	Agents configuration. When set, requires an agent_toolset_20260401 tool entry

Example request

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:

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

{
  "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
system	string	System prompt
tools	array of Agent tool	Tool configuration list
mcp_servers	array of MCP server	MCP server configuration
skills	array of Skill binding	Skill bindings
metadata	Metadata object	Custom metadata
multiagent	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 is not a string; the error message is Field 'name' must be a string.
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 for the full error envelope.

Error response example

{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "invalid_request_error",
    "message": "name must be between 1 and 256 characters"
  }
}

Related

Agent setup

Create a reusable, versioned agent configuration.