Create Agent

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

string

required

Agent name (2-100 characters). Used for identification in the UI.

boolean

default:false

Whether this agent should be the default for new threads. Only one agent can be default per account.

string

default:"bot"

Icon identifier from the icon library (e.g., “bot”, “code”, “brain”, “sparkles”).

string

default:"#000000"

Icon color in hex format (e.g., “#6366F1”).

string

default:"#F3F4F6"

Icon background color in hex format.

string

Custom system prompt for the agent. If not provided, uses default Suna configuration.

array

default:[]

Array of configured MCP (Model Context Protocol) integrations.

Show MCP Configuration Object

string

ID of the MCP server configuration

boolean

Whether this MCP is enabled

array

default:[]

Array of custom MCP server configurations.

Show Custom MCP Object

string

Name of the custom MCP server

string

Command to start the MCP server

array

Command line arguments

object

Environment variables

object

Tool configurations. Core tools (bash, read, write, edit, glob, grep) are automatically enabled.

Show Tool Configuration Structure

{
  "bash": { "enabled": true },
  "read": { "enabled": true },
  "write": { "enabled": true },
  "edit": { "enabled": true },
  "glob": { "enabled": true },
  "grep": { "enabled": true },
  "web_search": { "enabled": false }
}

Response

Returns the created agent with full configuration including the initial version (v1).

string

Unique identifier for the agent (UUID format)

string

Agent name

string

Agent description

string

Icon identifier

string

Icon color in hex format

string

Icon background color in hex format

boolean

Whether this is the default agent

string

ID of the current active version

integer

Total number of versions (starts at 1)

object

Full version configuration object

Show Version Object

string

Version UUID

integer

Sequential version number (1, 2, 3…)

string

Version label (e.g., “v1”, “v2”)

string

System prompt for this version

string

AI model identifier (e.g., “kortix/basic”)

array

Configured MCP integrations

array

Custom MCP servers

object

Tool configurations

string

ISO 8601 timestamp

string

ISO 8601 timestamp of creation

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
  }'

from kortix import Kortix

client = Kortix(api_key="YOUR_API_KEY")

agent = client.agents.create(
    name="Code Assistant",
    icon_name="code",
    icon_color="#6366F1",
    icon_background="#EEF2FF",
    is_default=False
)

print(f"Created agent: {agent.agent_id}")
print(f"Version: {agent.current_version.version_name}")

import { Kortix } from '@kortix/sdk';

const client = new Kortix({ apiKey: 'YOUR_API_KEY' });

const agent = await client.agents.create({
  name: 'Code Assistant',
  iconName: 'code',
  iconColor: '#6366F1',
  iconBackground: '#EEF2FF',
  isDefault: false,
});

console.log(`Created agent: ${agent.agentId}`);
console.log(`Version: ${agent.currentVersion.versionName}`);

const axios = require('axios');

const response = await axios.post(
  'https://api.kortix.ai/agents',
  {
    name: 'Code Assistant',
    icon_name: 'code',
    icon_color: '#6366F1',
    icon_background: '#EEF2FF',
    is_default: false,
  },
  {
    headers: {
      'Authorization': `Bearer ${process.env.KORTIX_API_KEY}`,
      'Content-Type': 'application/json',
    },
  }
);

const agent = response.data;
console.log('Agent created:', agent.agent_id);

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

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"
  }
}

error

Invalid request data (e.g., missing name, invalid icon)

{
  "detail": "Agent name is required"
}

error

Missing or invalid authentication token

{
  "detail": "Not authenticated"
}

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

Update Agent - Modify agent configuration
Get Agent - Retrieve agent details
Delete Agent - Remove an agent
Run Agent - Start an agent run

Getting Started

Agents

Threads

Tools

SDK

Endpoint

Authentication

Description

Limits

Request Body

Response

Examples

Response Example

Error Responses

Notes

​Endpoint

​Authentication

​Description

​Limits

​Request Body

​Response

​Examples

​Response Example

​Error Responses

​Notes

​Related Endpoints

Endpoint

Authentication

Description

Limits

Request Body

Response

Examples

Response Example

Error Responses

Notes

Related Endpoints