Skip to main content
POST
/
v2
/
chat
/
agents
Create agent
curl --request POST \
  --url https://api.agntix.ai/v2/chat/agents \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "fullName": "Customer Support Bot",
  "description": "Handles tier-1 customer queries",
  "role": "You are a helpful, concise support agent for Acme Inc. Always greet the user by name if available.",
  "language": "en",
  "systemPrompt": "You specialize in billing, returns, and account access.",
  "modelId": "96f3b0a3-1234-5678-abcd-ef1234567890",
  "tools": [
    {
      "toolId": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}
'
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "fullName": "Customer Support Bot",
  "description": "Handles tier-1 customer queries",
  "role": "You are a helpful, concise support agent for Acme Inc.",
  "language": "en",
  "voiceEnabled": false,
  "isActive": true,
  "isPublic": false,
  "orgId": "org_2abc123",
  "createdAt": "2026-04-29T08:00:00Z",
  "updatedAt": "2026-04-29T08:00:00Z"
}
Every endpoint on this page requires either a Clerk-issued JWT (Authorization: Bearer <token>) or an organization API key (x-api-key: pk_…). Anonymous calls return 401 Unauthorized. See Authentication for the full setup.
Use GET /v1/chat/models to get a valid modelId before creating an agent.

​
Code examples

curl -X POST https://api.agntix.ai/v2/chat/agents \
  -H "x-api-key: pk_live_••••" \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "Customer Support Bot",
    "description": "Handles tier-1 customer queries",
    "role": "You are a helpful, concise support agent for Acme Inc.",
    "language": "en",
    "systemPrompt": "You specialize in billing, returns, and account access. Keep responses under 3 sentences.",
    "modelId": "96f3b0a3-1234-5678-abcd-ef1234567890"
  }'

​
Creating a voice agent

To create an agent capable of handling phone calls, add voiceEnabled: true and pick a voicePipelineMode: 
curl -X POST https://api.agntix.ai/v2/chat/agents \
  -H "x-api-key: pk_live_••••" \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "Inbound Receptionist",
    "description": "Answers inbound calls and routes to the correct department",
    "role": "You are a professional phone receptionist for Acme Inc.",
    "language": "en",
    "modelId": "96f3b0a3-1234-5678-abcd-ef1234567890",
    "voiceEnabled": true,
    "voicePipelineMode": "pipeline",
    "sttModelId": "deepgram-nova-2-uuid",
    "ttsModelId": "eleven-turbo-uuid"
  }'

​
Sample response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "fullName": "Customer Support Bot",
  "description": "Handles tier-1 customer queries",
  "role": "You are a helpful, concise support agent for Acme Inc.",
  "language": "en",
  "systemPrompt": "You specialize in billing, returns, and account access.",
  "voiceEnabled": false,
  "isActive": true,
  "isPublic": false,
  "orgId": "org_2abc123",
  "modelId": "96f3b0a3-1234-5678-abcd-ef1234567890",
  "createdAt": "2026-04-29T08:00:00Z",
  "updatedAt": "2026-04-29T08:00:00Z"
}

Authorizations

​
x-api-key
string
header
required

Organization API key. Obtain from the dashboard. Format: pk_live_…

Body

application/json
​
fullName
string
required

Display name for the agent.

Example:

"Customer Support Bot"

​
description
string
required

Internal description of the agent's purpose.

Example:

"Handles tier-1 customer queries for Acme Inc."

​
role
string
required

The agent's persona and behavioral role. Used as the system prompt prefix.

Example:

"You are a helpful, concise support agent for Acme Inc."

​
language
string

BCP-47 language code. Controls TTS voice language selection.

Example:

"en"

​
systemPrompt
string

Additional system-level instructions appended to the role.

Example:

"You specialize in billing, returns, and account access. Keep responses under 3 sentences."

​
specialInstructions
string

Low-priority supplemental instructions (injected after system prompt).

​
modelId
string<uuid>

UUID of the LLM to use. Get IDs from GET /v1/chat/models.

​
sttModelId
string<uuid>

UUID of the Speech-to-Text model (voice agents only).

​
ttsModelId
string<uuid>

UUID of the Text-to-Speech model (voice agents only).

​
voiceEnabled
boolean
default:false

Enable voice capability. Requires voicePipelineMode when true.

​
voicePipelineMode
enum<string>

Voice pipeline mode. pipeline = TTS+STT, sts = speech-to-speech, hybrid = adaptive.

Available options:
pipeline,
sts,
hybrid
​
knowledgeStoreId
string

ID of a knowledge store to attach for RAG-based answers.

​
tools
object[]

Tools to attach to the agent at creation time.

​
welcomeAllowInterruptions
boolean

Whether the welcome prompt can be interrupted by the user (voice only).

Response

Agent created successfully.

​
id
string<uuid>
Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

​
fullName
string
Example:

"Customer Support Bot"

​
description
string
Example:

"Handles tier-1 customer queries"

​
role
string
Example:

"You are a helpful support agent for Acme Inc."

​
language
string
Example:

"en"

​
systemPrompt
string
​
voiceEnabled
boolean
Example:

false

​
voicePipelineMode
string | null
​
isActive
boolean
Example:

true

​
isPublic
boolean
Example:

false

​
orgId
string
Example:

"org_2abc123"

​
modelId
string<uuid>
​
createdAt
string<date-time>
Example:

"2026-04-28T11:42:11Z"

​
updatedAt
string<date-time>
Example:

"2026-04-28T11:42:11Z"