Skip to main content
POST /v1/agents Creates a new Agent configuration.

​
Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT>
Content-TypeYesapplication/json
Idempotency-KeyNoIdempotency key to prevent duplicate creation

​
Request body

FieldTypeRequiredDescription
namestringYesAgent name, 1-256 characters
modelstringYesModel identifier, such as "ultimate". Use List models to discover available values
systemstringNoSystem prompt, at most 100000 characters
descriptionstringNoAgent description, at most 2048 characters
toolsarray of Agent toolNoTool configuration list, up to 128 entries
mcp_serversarray of MCP serverNoMCP server configuration list, up to 20 entries. Authentication is configured through Vaults.
skillsarray of Skill bindingNoSkill bindings, up to 20 entries
metadataMetadata objectNoCustom metadata. Defaults to {}
multiagentMultiagentNoManaged 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": "http",
        "name": "weather-service",
        "url": "https://mcp.example.com/mcp"
      }
    ]
  }'

​
Example response

HTTP 201 Created 
{
  "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": "http",
      "name": "weather-service",
      "url": "https://mcp.example.com/mcp"
    }
  ],
  "skills": [],
  "metadata": {},
  "version": 1,
  "archived": false,
  "archived_at": null,
  "created_at": "2026-05-18T15:26:39.61669Z",
  "updated_at": "2026-05-18T15:26:39.61669Z"
}

​
Response fields

FieldTypeDescription
typestringAlways "agent"
idstringAgent unique identifier with the agent_ prefix
namestringAgent name
descriptionstringAgent description
modelstringModel identifier
systemstringSystem prompt
toolsarray of Agent toolTool configuration list
mcp_serversarray of MCP serverMCP server configuration
skillsarray of Skill bindingSkill bindings
metadataMetadata objectCustom metadata
multiagentMultiagent | nullManaged Agents configuration, null when not set
versionintegerCurrent version, starting at 1
archivedbooleanWhether archived (default false)
archived_atstring|nullArchive time (ISO 8601), null when not archived
created_atstringCreation time (ISO 8601)
updated_atstringLast update time (ISO 8601)

​
Errors

HTTPTypeTrigger
400invalid_request_errorMissing required field name
400invalid_request_errorname exceeds 256 characters
400invalid_request_errorMissing required field model
400invalid_request_errortools exceeds the maximum of 128 entries
400invalid_request_errorInvalid mcp_servers or skills configuration
400invalid_request_errorskills exceeds the maximum of 20 entries
400invalid_request_errormultiagent.type is not "coordinator"
400invalid_request_errormultiagent.agents is empty or exceeds the maximum of 20 entries
400invalid_request_errormultiagent is set but tools is missing an agent_toolset_20260401 entry
400invalid_request_errorAgent ID referenced in multiagent.agents does not exist
401authentication_errorPAT invalid or expired
403permission_errorNot authorized for this operation
See Errors for the full error envelope.

​
Error response example

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "name must be between 1 and 256 characters"
  }
}

Agent setup

Create a reusable, versioned agent configuration.