Create Agent

POST

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

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'}]
  })
};

fetch('https://api.agntix.ai/v2/chat/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.agntix.ai/v2/chat/agents"

payload = {
    "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" }]
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

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

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "fullName should not be empty",
    "status": 400
  },
  "meta": {
    "requestId": "req_01j3m...",
    "timestamp": "2026-04-29T10:00:00Z"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required.",
    "status": 401
  },
  "meta": {
    "requestId": "req_01j3m...",
    "timestamp": "2026-04-29T10: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"
  }'

const res = await fetch('https://api.agntix.ai/v2/chat/agents', {
  method: 'POST',
  headers: {
    'x-api-key': 'pk_live_••••',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    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.',
    modelId: '96f3b0a3-1234-5678-abcd-ef1234567890',
    tools: [{ toolId: '550e8400-e29b-41d4-a716-446655440000' }],
  }),
});
const agent = await res.json();
console.log('Created agent:', agent.id);

import httpx

agent = httpx.post(
    "https://api.agntix.ai/v2/chat/agents",
    headers={"x-api-key": "pk_live_••••"},
    json={
        "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.",
        "modelId": "96f3b0a3-1234-5678-abcd-ef1234567890",
    },
).json()
print("Created agent:", agent["id"])

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

const agent = await fetch('https://api.agntix.ai/v2/chat/agents', {
  method: 'POST',
  headers: {
    'x-api-key': 'pk_live_••••',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    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',
  }),
}).then(r => r.json());

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.

Show child attributes

welcomeAllowInterruptions

boolean

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

Response

Agent created successfully.

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"

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

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'}]
  })
};

fetch('https://api.agntix.ai/v2/chat/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.agntix.ai/v2/chat/agents"

payload = {
    "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" }]
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

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

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "fullName should not be empty",
    "status": 400
  },
  "meta": {
    "requestId": "req_01j3m...",
    "timestamp": "2026-04-29T10:00:00Z"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required.",
    "status": 401
  },
  "meta": {
    "requestId": "req_01j3m...",
    "timestamp": "2026-04-29T10:00:00Z"
  }
}

Overview

Agents

Chat

Voice

Tools

Phone Numbers

Code examples

Creating a voice agent

Sample response

Authorizations

Body

Response

​Code examples

​Creating a voice agent

​Sample response

Authorizations

Body

Response

Code examples

Creating a voice agent

Sample response