Skip to main content
POST
/
agents
Create Agent
curl --request POST \
  --url https://api.example.com/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "default_user_lang": "<string>",
  "thinking_lang": "<string>",
  "description": "<string>",
  "default_voice_id": "<string>",
  "interruptions_enabled": true,
  "escalation_policy": {},
  "model_provider": "openai",
  "model_name": "gpt-4o-mini",
  "temperature": 0.7,
  "max_tokens": 150,
  "system_prompt": "<string>",
  "persona": "<string>",
  "first_message_mode": "assistant-speaks-first",
  "first_message_script": "<string>",
  "voice_provider": "elevenlabs",
  "voice_id": "<string>",
  "background_sound_url": "<string>",
  "input_min_characters": 30,
  "transcriber_provider": "deepgram",
  "transcriber_model": "nova-3",
  "background_denoising": true,
  "confidence_threshold": 0.4,
  "multilingual_enabled": false,
  "supported_languages": [
    "<string>"
  ],
  "language_detection_provider": "auto",
  "respond_in_user_language": true,
  "wait_seconds": 0.4,
  "smart_endpointing": true,
  "interruption_words": 3,
  "punctuation_boundary_ms": 100,
  "no_punctuation_boundary_ms": 1500,
  "silence_timeout_seconds": 30,
  "max_duration_seconds": 600,
  "idle_messages_enabled": true,
  "max_idle_messages": 3,
  "idle_timeout_seconds": 7.5,
  "analysis_prompt": "<string>",
  "analysis_timeout_sec": 10,
  "min_messages_for_analysis": 2,
  "voicemail_detection_enabled": true,
  "voicemail_message": "<string>",
  "end_call_message": "<string>",
  "keypad_input_enabled": false,
  "keypad_timeout_seconds": 2,
  "keypad_delimiters": "#",
  "sip_enabled": false,
  "recording_enabled": true,
  "analytics_enabled": true,
  "knowledge": [
    {}
  ],
  "tools": [
    {}
  ],
  "channels": {}
}
'
import requests

url = "https://api.example.com/agents"

payload = {
    "name": "<string>",
    "default_user_lang": "<string>",
    "thinking_lang": "<string>",
    "description": "<string>",
    "default_voice_id": "<string>",
    "interruptions_enabled": True,
    "escalation_policy": {},
    "model_provider": "openai",
    "model_name": "gpt-4o-mini",
    "temperature": 0.7,
    "max_tokens": 150,
    "system_prompt": "<string>",
    "persona": "<string>",
    "first_message_mode": "assistant-speaks-first",
    "first_message_script": "<string>",
    "voice_provider": "elevenlabs",
    "voice_id": "<string>",
    "background_sound_url": "<string>",
    "input_min_characters": 30,
    "transcriber_provider": "deepgram",
    "transcriber_model": "nova-3",
    "background_denoising": True,
    "confidence_threshold": 0.4,
    "multilingual_enabled": False,
    "supported_languages": ["<string>"],
    "language_detection_provider": "auto",
    "respond_in_user_language": True,
    "wait_seconds": 0.4,
    "smart_endpointing": True,
    "interruption_words": 3,
    "punctuation_boundary_ms": 100,
    "no_punctuation_boundary_ms": 1500,
    "silence_timeout_seconds": 30,
    "max_duration_seconds": 600,
    "idle_messages_enabled": True,
    "max_idle_messages": 3,
    "idle_timeout_seconds": 7.5,
    "analysis_prompt": "<string>",
    "analysis_timeout_sec": 10,
    "min_messages_for_analysis": 2,
    "voicemail_detection_enabled": True,
    "voicemail_message": "<string>",
    "end_call_message": "<string>",
    "keypad_input_enabled": False,
    "keypad_timeout_seconds": 2,
    "keypad_delimiters": "#",
    "sip_enabled": False,
    "recording_enabled": True,
    "analytics_enabled": True,
    "knowledge": [{}],
    "tools": [{}],
    "channels": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    default_user_lang: '<string>',
    thinking_lang: '<string>',
    description: '<string>',
    default_voice_id: '<string>',
    interruptions_enabled: true,
    escalation_policy: {},
    model_provider: 'openai',
    model_name: 'gpt-4o-mini',
    temperature: 0.7,
    max_tokens: 150,
    system_prompt: '<string>',
    persona: '<string>',
    first_message_mode: 'assistant-speaks-first',
    first_message_script: '<string>',
    voice_provider: 'elevenlabs',
    voice_id: '<string>',
    background_sound_url: '<string>',
    input_min_characters: 30,
    transcriber_provider: 'deepgram',
    transcriber_model: 'nova-3',
    background_denoising: true,
    confidence_threshold: 0.4,
    multilingual_enabled: false,
    supported_languages: ['<string>'],
    language_detection_provider: 'auto',
    respond_in_user_language: true,
    wait_seconds: 0.4,
    smart_endpointing: true,
    interruption_words: 3,
    punctuation_boundary_ms: 100,
    no_punctuation_boundary_ms: 1500,
    silence_timeout_seconds: 30,
    max_duration_seconds: 600,
    idle_messages_enabled: true,
    max_idle_messages: 3,
    idle_timeout_seconds: 7.5,
    analysis_prompt: '<string>',
    analysis_timeout_sec: 10,
    min_messages_for_analysis: 2,
    voicemail_detection_enabled: true,
    voicemail_message: '<string>',
    end_call_message: '<string>',
    keypad_input_enabled: false,
    keypad_timeout_seconds: 2,
    keypad_delimiters: '#',
    sip_enabled: false,
    recording_enabled: true,
    analytics_enabled: true,
    knowledge: [{}],
    tools: [{}],
    channels: {}
  })
};

fetch('https://api.example.com/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/agents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'default_user_lang' => '<string>',
    'thinking_lang' => '<string>',
    'description' => '<string>',
    'default_voice_id' => '<string>',
    'interruptions_enabled' => true,
    'escalation_policy' => [
        
    ],
    'model_provider' => 'openai',
    'model_name' => 'gpt-4o-mini',
    'temperature' => 0.7,
    'max_tokens' => 150,
    'system_prompt' => '<string>',
    'persona' => '<string>',
    'first_message_mode' => 'assistant-speaks-first',
    'first_message_script' => '<string>',
    'voice_provider' => 'elevenlabs',
    'voice_id' => '<string>',
    'background_sound_url' => '<string>',
    'input_min_characters' => 30,
    'transcriber_provider' => 'deepgram',
    'transcriber_model' => 'nova-3',
    'background_denoising' => true,
    'confidence_threshold' => 0.4,
    'multilingual_enabled' => false,
    'supported_languages' => [
        '<string>'
    ],
    'language_detection_provider' => 'auto',
    'respond_in_user_language' => true,
    'wait_seconds' => 0.4,
    'smart_endpointing' => true,
    'interruption_words' => 3,
    'punctuation_boundary_ms' => 100,
    'no_punctuation_boundary_ms' => 1500,
    'silence_timeout_seconds' => 30,
    'max_duration_seconds' => 600,
    'idle_messages_enabled' => true,
    'max_idle_messages' => 3,
    'idle_timeout_seconds' => 7.5,
    'analysis_prompt' => '<string>',
    'analysis_timeout_sec' => 10,
    'min_messages_for_analysis' => 2,
    'voicemail_detection_enabled' => true,
    'voicemail_message' => '<string>',
    'end_call_message' => '<string>',
    'keypad_input_enabled' => false,
    'keypad_timeout_seconds' => 2,
    'keypad_delimiters' => '#',
    'sip_enabled' => false,
    'recording_enabled' => true,
    'analytics_enabled' => true,
    'knowledge' => [
        [
                
        ]
    ],
    'tools' => [
        [
                
        ]
    ],
    'channels' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/agents"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"default_user_lang\": \"<string>\",\n  \"thinking_lang\": \"<string>\",\n  \"description\": \"<string>\",\n  \"default_voice_id\": \"<string>\",\n  \"interruptions_enabled\": true,\n  \"escalation_policy\": {},\n  \"model_provider\": \"openai\",\n  \"model_name\": \"gpt-4o-mini\",\n  \"temperature\": 0.7,\n  \"max_tokens\": 150,\n  \"system_prompt\": \"<string>\",\n  \"persona\": \"<string>\",\n  \"first_message_mode\": \"assistant-speaks-first\",\n  \"first_message_script\": \"<string>\",\n  \"voice_provider\": \"elevenlabs\",\n  \"voice_id\": \"<string>\",\n  \"background_sound_url\": \"<string>\",\n  \"input_min_characters\": 30,\n  \"transcriber_provider\": \"deepgram\",\n  \"transcriber_model\": \"nova-3\",\n  \"background_denoising\": true,\n  \"confidence_threshold\": 0.4,\n  \"multilingual_enabled\": false,\n  \"supported_languages\": [\n    \"<string>\"\n  ],\n  \"language_detection_provider\": \"auto\",\n  \"respond_in_user_language\": true,\n  \"wait_seconds\": 0.4,\n  \"smart_endpointing\": true,\n  \"interruption_words\": 3,\n  \"punctuation_boundary_ms\": 100,\n  \"no_punctuation_boundary_ms\": 1500,\n  \"silence_timeout_seconds\": 30,\n  \"max_duration_seconds\": 600,\n  \"idle_messages_enabled\": true,\n  \"max_idle_messages\": 3,\n  \"idle_timeout_seconds\": 7.5,\n  \"analysis_prompt\": \"<string>\",\n  \"analysis_timeout_sec\": 10,\n  \"min_messages_for_analysis\": 2,\n  \"voicemail_detection_enabled\": true,\n  \"voicemail_message\": \"<string>\",\n  \"end_call_message\": \"<string>\",\n  \"keypad_input_enabled\": false,\n  \"keypad_timeout_seconds\": 2,\n  \"keypad_delimiters\": \"#\",\n  \"sip_enabled\": false,\n  \"recording_enabled\": true,\n  \"analytics_enabled\": true,\n  \"knowledge\": [\n    {}\n  ],\n  \"tools\": [\n    {}\n  ],\n  \"channels\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.example.com/agents")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"default_user_lang\": \"<string>\",\n  \"thinking_lang\": \"<string>\",\n  \"description\": \"<string>\",\n  \"default_voice_id\": \"<string>\",\n  \"interruptions_enabled\": true,\n  \"escalation_policy\": {},\n  \"model_provider\": \"openai\",\n  \"model_name\": \"gpt-4o-mini\",\n  \"temperature\": 0.7,\n  \"max_tokens\": 150,\n  \"system_prompt\": \"<string>\",\n  \"persona\": \"<string>\",\n  \"first_message_mode\": \"assistant-speaks-first\",\n  \"first_message_script\": \"<string>\",\n  \"voice_provider\": \"elevenlabs\",\n  \"voice_id\": \"<string>\",\n  \"background_sound_url\": \"<string>\",\n  \"input_min_characters\": 30,\n  \"transcriber_provider\": \"deepgram\",\n  \"transcriber_model\": \"nova-3\",\n  \"background_denoising\": true,\n  \"confidence_threshold\": 0.4,\n  \"multilingual_enabled\": false,\n  \"supported_languages\": [\n    \"<string>\"\n  ],\n  \"language_detection_provider\": \"auto\",\n  \"respond_in_user_language\": true,\n  \"wait_seconds\": 0.4,\n  \"smart_endpointing\": true,\n  \"interruption_words\": 3,\n  \"punctuation_boundary_ms\": 100,\n  \"no_punctuation_boundary_ms\": 1500,\n  \"silence_timeout_seconds\": 30,\n  \"max_duration_seconds\": 600,\n  \"idle_messages_enabled\": true,\n  \"max_idle_messages\": 3,\n  \"idle_timeout_seconds\": 7.5,\n  \"analysis_prompt\": \"<string>\",\n  \"analysis_timeout_sec\": 10,\n  \"min_messages_for_analysis\": 2,\n  \"voicemail_detection_enabled\": true,\n  \"voicemail_message\": \"<string>\",\n  \"end_call_message\": \"<string>\",\n  \"keypad_input_enabled\": false,\n  \"keypad_timeout_seconds\": 2,\n  \"keypad_delimiters\": \"#\",\n  \"sip_enabled\": false,\n  \"recording_enabled\": true,\n  \"analytics_enabled\": true,\n  \"knowledge\": [\n    {}\n  ],\n  \"tools\": [\n    {}\n  ],\n  \"channels\": {}\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.example.com/agents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"default_user_lang\": \"<string>\",\n  \"thinking_lang\": \"<string>\",\n  \"description\": \"<string>\",\n  \"default_voice_id\": \"<string>\",\n  \"interruptions_enabled\": true,\n  \"escalation_policy\": {},\n  \"model_provider\": \"openai\",\n  \"model_name\": \"gpt-4o-mini\",\n  \"temperature\": 0.7,\n  \"max_tokens\": 150,\n  \"system_prompt\": \"<string>\",\n  \"persona\": \"<string>\",\n  \"first_message_mode\": \"assistant-speaks-first\",\n  \"first_message_script\": \"<string>\",\n  \"voice_provider\": \"elevenlabs\",\n  \"voice_id\": \"<string>\",\n  \"background_sound_url\": \"<string>\",\n  \"input_min_characters\": 30,\n  \"transcriber_provider\": \"deepgram\",\n  \"transcriber_model\": \"nova-3\",\n  \"background_denoising\": true,\n  \"confidence_threshold\": 0.4,\n  \"multilingual_enabled\": false,\n  \"supported_languages\": [\n    \"<string>\"\n  ],\n  \"language_detection_provider\": \"auto\",\n  \"respond_in_user_language\": true,\n  \"wait_seconds\": 0.4,\n  \"smart_endpointing\": true,\n  \"interruption_words\": 3,\n  \"punctuation_boundary_ms\": 100,\n  \"no_punctuation_boundary_ms\": 1500,\n  \"silence_timeout_seconds\": 30,\n  \"max_duration_seconds\": 600,\n  \"idle_messages_enabled\": true,\n  \"max_idle_messages\": 3,\n  \"idle_timeout_seconds\": 7.5,\n  \"analysis_prompt\": \"<string>\",\n  \"analysis_timeout_sec\": 10,\n  \"min_messages_for_analysis\": 2,\n  \"voicemail_detection_enabled\": true,\n  \"voicemail_message\": \"<string>\",\n  \"end_call_message\": \"<string>\",\n  \"keypad_input_enabled\": false,\n  \"keypad_timeout_seconds\": 2,\n  \"keypad_delimiters\": \"#\",\n  \"sip_enabled\": false,\n  \"recording_enabled\": true,\n  \"analytics_enabled\": true,\n  \"knowledge\": [\n    {}\n  ],\n  \"tools\": [\n    {}\n  ],\n  \"channels\": {}\n}"

response = http.request(request)
puts response.read_body
{
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "version": 123,
  "livekit": {},
  "embed": {},
  "sip": {},
  "capabilities": {},
  "tools": [],
  "workflow": {},
  "client_messages": [
    "conversation-update",
    "tool-calls",
    "transcript.partial",
    "transcript.final"
  ]
}
{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Agent creation model.

​
name
string
required
Required string length: 1 - 255
​
default_user_lang
string
required
Required string length: 2 - 10
​
thinking_lang
string
required
Required string length: 2 - 10
​
description
string | null
​
default_voice_id
string | null
​
interruptions_enabled
boolean
default:true
​
escalation_policy
Escalation Policy · object | null
​
model_provider
string
default:openai
Pattern: ^(openai|azure_openai|anthropic|google|groq|cerebras|deepseek|xai|perplexity|together|amazon_bedrock|anyscale|openrouter|deepinfra)$
​
model_name
string
default:gpt-4o-mini
Required string length: 1 - 100
​
temperature
number
default:0.7
Required range: 0 <= x <= 1
​
max_tokens
integer
default:150
Required range: 50 <= x <= 1000
​
system_prompt
string | null

Full system prompt defining the agent's role, behavior, and instructions. Falls back to description if not set.

Maximum string length: 8000
​
persona
string | null

Short character/personality descriptor (e.g. 'Friendly British accountant'). Renders as 'Personality: ...' in the system prompt.

Maximum string length: 2000
​
first_message_mode
string
default:assistant-speaks-first
Pattern: ^(assistant-speaks-first|wait-for-user|assistant-speaks-first-with-model-generated-message)$
​
first_message_script
string | null
Maximum string length: 500
​
voice_provider
string
default:elevenlabs
Pattern: ^(elevenlabs|cartesia|openai|deepgram|google|azure|rime|lmnt)$
​
voice_id
string | null
​
background_sound_url
string | null
Maximum string length: 500
​
input_min_characters
integer
default:30
Required range: 10 <= x <= 100
​
transcriber_provider
string
default:deepgram
Pattern: ^(deepgram|openai|assemblyai|google|azure)$
​
transcriber_model
string
default:nova-3
Required string length: 1 - 100
​
background_denoising
boolean
default:true
​
confidence_threshold
number
default:0.4
Required range: 0 <= x <= 1
​
multilingual_enabled
boolean
default:false

Enable automatic language detection for multilingual conversations

​
supported_languages
string[] | null

List of language codes the agent supports (e.g., ['en', 'es', 'fr']). If multilingual_enabled=true and this is empty, all languages are supported.

​
language_detection_provider
string
default:auto

Provider for language detection: 'auto' uses STT provider's built-in detection

Pattern: ^(auto|deepgram|whisper)$
​
respond_in_user_language
boolean
default:true

When true, agent responds in the detected user language. When false, always responds in default_user_lang.

​
wait_seconds
number
default:0.4
Required range: 0.1 <= x <= 1
​
smart_endpointing
boolean
default:true
​
interruption_words
integer
default:3
Required range: 0 <= x <= 10
​
punctuation_boundary_ms
integer
default:100
Required range: 50 <= x <= 500
​
no_punctuation_boundary_ms
integer
default:1500
Required range: 800 <= x <= 3000
​
silence_timeout_seconds
integer
default:30
Required range: 10 <= x <= 120
​
max_duration_seconds
integer
default:600
Required range: 180 <= x <= 1800
​
idle_messages_enabled
boolean
default:true
​
max_idle_messages
integer
default:3
Required range: 1 <= x <= 10
​
idle_timeout_seconds
number
default:7.5
Required range: 5 <= x <= 60
​
analysis_prompt
string | null
Maximum string length: 2000
​
analysis_timeout_sec
integer
default:10
Required range: 1 <= x <= 60
​
min_messages_for_analysis
integer
default:2
Required range: 0 <= x <= 10
​
voicemail_detection_enabled
boolean
default:true
​
voicemail_message
string | null
Maximum string length: 500
​
end_call_message
string | null
Maximum string length: 500
​
keypad_input_enabled
boolean
default:false
​
keypad_timeout_seconds
integer
default:2
Required range: 1 <= x <= 6
​
keypad_delimiters
string
default:#
Pattern: ^[#*]+$
​
sip_enabled
boolean
default:false

Enable SIP/phone calling for this agent

​
recording_enabled
boolean
default:true

Enable call recording for this agent

​
analytics_enabled
boolean
default:true

Enable analytics tracking for this agent

​
knowledge
Knowledge · object[] | null
​
tools
Tools · object[] | null
​
channels
Channels · object | null

Response

Successful Response

Agent creation response model.

​
agent_id
string<uuid>
required
​
version
integer
required
​
livekit
Livekit · object
required
​
embed
Embed · object
required
​
sip
Sip · object | null
​
capabilities
Capabilities · object | null
​
tools
Tools · object[]
​
workflow
Workflow · object | null
​
client_messages
string[]