Skip to main content
POST
Create a new AI agent.

Authorizations

X-API-Key
string
header
required

Company API key - scoped to a specific company. Generate from the Integrations page in your dashboard.

Body

application/json

Agent configuration

Request body for creating a new agent

name
string
required

Agent name

avatarImage
string

URL or base64 avatar image

systemPrompt
string

AI system instructions

agentPrompt
string

Agent-specific prompt

customColors
object

Branding colors: {primary?: string (hex), secondary?: string (hex), background?: string (hex)}

model
string

AI model (default: gpt-4o-mini)

channelSettings
object

Multi-channel configuration: {website?: {enabled: boolean}, email?: {enabled: boolean, address?: string}, sms?: {enabled: boolean, phoneNumber?: string}, whatsapp?: {enabled: boolean, phoneNumber?: string (Twilio WhatsApp-enabled number, E.164), integrationId?: string (Twilio integration ID), autoReply?: boolean}, voice?: {enabled: boolean}}

leadFields
object[]

Lead field definitions: [{name: string, type: string (text, email, phone, number), required?: boolean}]

contactListId
string

Smart list ID for contact collection

aiContactCaptureEnabled
boolean

Whether AI passively extracts contact info from conversations (default: true)

isActive
boolean

Whether agent is active (default: true)

knowledgeBaseEnabled
boolean

Whether the agent answers from the knowledge base

knowledgeBaseScope
string

Knowledge base folder the agent is limited to (e.g. / or /shared/Support)

multiStepToolsEnabled
boolean

Whether the agent can chain multiple tool-calling turns (knowledge base search, MCP servers, integration toolsets) instead of a single round

multiStepMaxTurns
integer

Tool-calling turns allowed before tools are removed and the agent must answer (1-10, default 5)

Response

The created agent

Agent object

id
string

Agent ID

name
string

Agent name

avatarImage
string

URL or base64 avatar image

systemPrompt
string

AI system instructions

agentPrompt
string

Agent-specific prompt

customColors
object

Branding colors configuration

model
string

AI model

channelSettings
object

Multi-channel configuration

leadFields
object[]

Lead field definitions

contactListId
string

Smart list ID

aiContactCaptureEnabled
boolean

Whether AI passively extracts contact info from conversations

isActive
boolean

Whether agent is active

knowledgeBaseEnabled
boolean

Whether the agent answers from the knowledge base

knowledgeBaseScope
string

Knowledge base folder the agent is limited to (e.g. / or /shared/Support)

multiStepToolsEnabled
boolean

Whether the agent can chain multiple tool-calling turns (knowledge base search, MCP servers, integration toolsets) instead of a single round

multiStepMaxTurns
integer

Tool-calling turns allowed before tools are removed and the agent must answer (1-10, default 5)

shortCode
string

Shareable URL code

created
number

Creation timestamp

updated
number

Last update timestamp