Skip to main content

​
Endpoint

POST /agents

​
Authentication

Requires JWT authentication via Authorization: Bearer <token> header.

​
Description

Creates a new AI agent with a custom name, icon, and initial configuration version. The agent is initialized with default tools and system prompt, which can be customized immediately or later via the update endpoint.

​
Limits

Agent creation is subject to tier-based limits:
  • Free tier: 3 agents maximum
  • Pro tier: 10 agents maximum
  • Enterprise tier: Unlimited agents
Exceeding the limit returns a 402 error with code AGENT_LIMIT_EXCEEDED.

​
Request Body

​
name
string
required
Agent name (2-100 characters). Used for identification in the UI.
​
is_default
boolean
default:false
Whether this agent should be the default for new threads. Only one agent can be default per account.
​
icon_name
string
default:"bot"
Icon identifier from the icon library (e.g., “bot”, “code”, “brain”, “sparkles”).
​
icon_color
string
default:"#000000"
Icon color in hex format (e.g., “#6366F1”).
​
icon_background
string
default:"#F3F4F6"
Icon background color in hex format.
​
system_prompt
string
Custom system prompt for the agent. If not provided, uses default Suna configuration.
​
configured_mcps
array
default:[]
Array of configured MCP (Model Context Protocol) integrations.
​
custom_mcps
array
default:[]
Array of custom MCP server configurations.
​
agentpress_tools
object
Tool configurations. Core tools (bash, read, write, edit, glob, grep) are automatically enabled.

​
Response

Returns the created agent with full configuration including the initial version (v1).
​
agent_id
string
Unique identifier for the agent (UUID format)
​
name
string
Agent name
​
description
string
Agent description
​
icon_name
string
Icon identifier
​
icon_color
string
Icon color in hex format
​
icon_background
string
Icon background color in hex format
​
is_default
boolean
Whether this is the default agent
​
current_version_id
string
ID of the current active version
​
version_count
integer
Total number of versions (starts at 1)
​
current_version
object
Full version configuration object
​
created_at
string
ISO 8601 timestamp of creation
​
updated_at
string
ISO 8601 timestamp of last update

​
Examples

curl -X POST https://api.kortix.ai/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Code Assistant",
    "icon_name": "code",
    "icon_color": "#6366F1",
    "icon_background": "#EEF2FF",
    "is_default": false
  }'

​
Response Example

{
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Code Assistant",
  "description": null,
  "icon_name": "code",
  "icon_color": "#6366F1",
  "icon_background": "#EEF2FF",
  "is_default": false,
  "is_public": false,
  "tags": [],
  "current_version_id": "660f9511-f3ac-52e5-b827-557766551111",
  "version_count": 1,
  "current_version": {
    "version_id": "660f9511-f3ac-52e5-b827-557766551111",
    "agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "version_number": 1,
    "version_name": "v1",
    "system_prompt": "You are an expert coding assistant. Help users write clean, efficient code and debug issues.",
    "model": "kortix/basic",
    "configured_mcps": [],
    "custom_mcps": [],
    "agentpress_tools": {
      "bash": { "enabled": true },
      "read": { "enabled": true },
      "write": { "enabled": true },
      "edit": { "enabled": true },
      "glob": { "enabled": true },
      "grep": { "enabled": true }
    },
    "is_active": true,
    "created_at": "2025-08-15T10:30:00.000Z",
    "updated_at": "2025-08-15T10:30:00.000Z"
  },
  "configured_mcps": [],
  "custom_mcps": [],
  "agentpress_tools": {
    "bash": { "enabled": true },
    "read": { "enabled": true },
    "write": { "enabled": true },
    "edit": { "enabled": true },
    "glob": { "enabled": true },
    "grep": { "enabled": true }
  },
  "created_at": "2025-08-15T10:30:00.000Z",
  "updated_at": "2025-08-15T10:30:00.000Z"
}

​
Error Responses

​
402 Payment Required
error
Agent limit exceeded for current tier
{
  "detail": {
    "message": "Maximum of 3 agents allowed for your current plan. You have 3 agents.",
    "current_count": 3,
    "limit": 3,
    "tier_name": "free",
    "error_code": "AGENT_LIMIT_EXCEEDED"
  }
}
​
400 Bad Request
error
Invalid request data (e.g., missing name, invalid icon)
{
  "detail": "Agent name is required"
}
​
401 Unauthorized
error
Missing or invalid authentication token
{
  "detail": "Not authenticated"
}
​
500 Internal Server Error
error
Server error during agent creation
{
  "detail": "Failed to create agent: <error details>"
}

​
Notes

  • Default Agent: Setting is_default: true automatically unsets any existing default agent
  • Versioning: Every agent starts with version v1, which is automatically created
  • Core Tools: The core tools (bash, read, write, edit, glob, grep) are always enabled and cannot be disabled
  • Icon Library: Use the /agents/generate-icon endpoint to get AI-suggested icons based on agent name
  • Cache: Creating an agent invalidates the agent count cache for the user

Build docs developers (and LLMs) love

Get started for freeTalk to us