curl --request POST \
  --url https://api.example.com/v3/ai-agents \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_name": "Support Agent",
  "language_code": "en-US",
  "speech_speed": 1,
  "vad_activation_threshold": 0.4,
  "welcome_message": "Hi, thanks for calling. How can I help?",
  "llm": {
    "llm_id": "9d259647-d5ec-423d-96a9-2750980e8ecb",
    "llm_type": "simple",
    "model_temperature": 0,
    "system_prompt": "You are a helpful assistant."
  },
  "stt": {
    "provider_id": "6a5c45808d2d94e9d0e255d3",
    "model_id": "aec2493a-eba9-48d0-9e64-4aab4437f7f5"
  },
  "tts": {
    "provider_id": "6a5c079f814b8ed08b15172b",
    "voice_id": "cgSgspJ2msm6clMCkdW9"
  }
}
'

{
  "status": "success",
  "message": "Simple agent created successfully",
  "data": {
    "ai_agent_id": "3f6c2a1e-8b4d-4c9a-9e2f-7d1b5a6c0e42",
    "agent_name": "Support Agent",
    "agent_status": "ACTIVE",
    "language_code": "en-US",
    "llm": {
      "llm_id": "9d259647-d5ec-423d-96a9-2750980e8ecb",
      "llm_type": "simple",
      "model_provider": "openai",
      "model_name": "gpt-4o-mini",
      "model_display_name": "GPT-4o mini",
      "model_temperature": 0,
      "max_tokens": 4096,
      "system_prompt": "You are a helpful assistant."
    },
    "stt": {
      "provider_id": "6a5c45808d2d94e9d0e255d3",
      "provider": "deepgram",
      "model_id": "aec2493a-eba9-48d0-9e64-4aab4437f7f5",
      "model": "nova-3"
    },
    "tts": {
      "provider_id": "6a5c079f814b8ed08b15172b",
      "provider": "elevenlabs",
      "voice_id": "cgSgspJ2msm6clMCkdW9",
      "voice_name": "Jessica",
      "model_name": "eleven_flash_v2_5",
      "voice_temperature": 0.2
    },
    "speech_speed": 1,
    "vad_activation_threshold": 0.4,
    "welcome_message": "Hi, thanks for calling. How can I help?",
    "enable_user_interruptions": true,
    "minimum_speech_duration_for_interruptions": 0.5,
    "minimum_words_before_interruption": 2,
    "interruption_mode": "vad",
    "ambient_sound": "none",
    "ambient_sound_volume": 1,
    "end_call_after_silence_seconds": 10,
    "max_call_duration_seconds": 1800,
    "voicemail_detection_timeout_seconds": 90,
    "agent_ended_call_delay_seconds": 2,
    "welcome_message_delay_in_seconds": 2,
    "enable_amd": false,
    "silence_reminder_enabled": false,
    "silence_reminder_duration_seconds": 10,
    "max_number_of_silence_reminders": 3,
    "interval_between_silence_reminders_seconds": 10,
    "organization_id": "org_7f3a9c",
    "agent_owner_id": "usr_12ab34",
    "created_by_user_id": "usr_12ab34",
    "created_at": "2026-10-15T09:30:12.481Z",
    "modified_at": "2026-10-15T09:30:12.481Z",
    "current_version": 1,
    "operation_type": "CREATE"
  }
}

AI Agents v3

Create AI Agent

Create an AI agent. The LLM, speech-to-text model and voice are chosen by catalog id. You no longer send provider names, model names or provider credentials.

The v2 equivalent, POST /v2/ai-agents/, is deprecated and stops working on November 30, 2026. This is the v3 endpoint. Migrate from v2 to v3 before that date.

References, not inline configuration

Field	What it references	Where to find the id
`llm.llm_id`	An LLM model in the model catalog	`llm_model_id` in List LLM models
`stt.provider_id`	A speech-to-text provider	`id` in List STT providers
`stt.model_id`	One of that provider’s models	`languages[].models[].id` in the same response
`tts.provider_id`	A text-to-speech provider	`id` in List TTS providers
`tts.voice_id`	One of that provider’s voices	`languages[].voices[].voice_id` in the same response

Every reference is resolved and checked before the agent is stored. The request returns 422 when a referenced record does not exist, is not ACTIVE, or does not support the requested llm_type. A custom LLM model must also belong to your organization. On success, the resolved provider, model and voice names are copied onto the agent and returned in the response.

Agent types

llm.llm_type is required. It selects the shape of the rest of the request.

simple: the root llm object carries llm_id and system_prompt. The root stt and tts objects carry the speech references. The response message is Simple agent created successfully and operation_type is CREATE.
flow: the root llm object carries only llm_type and graph_data. The flow-default references live in graph_data.agentDefaults (stt.provider_id + stt.model_id, llm.llm_id, tts.provider_id + tts.voice_id). The server fills provider, model and voice names into the graph before it validates the graph. The response message is Flow builder agent created successfully and operation_type is CREATE_FLOW_BUILDER. In the response, the root llm also carries llm_id, model_provider, model_name, model_display_name, model_temperature and max_tokens, filled from the flow-default model. A flow agent has no root stt, tts, agent_owner_id or pronunciations.
agentic: rejected.

Agentic agent creation is discontinued. llm_type: "agentic" returns 422 with Agentic agent creation is no longer supported. Existing agentic agents stay readable and updatable. Use flow for new multi-step agents.

Field notes

model_temperature: when omitted, the agent takes the catalog model’s temperature. A sent value, 0 included, is stored as is. The service enforces no bounds; the console allows 0–2.
max_tokens is filled from the model catalog.
vad_activation_threshold: 0.10–0.90, no default. When unset, the key is omitted from the response and the call handler uses its own per-language default.
wait_time_before_detecting_end_of_speech and max_endpointing_delay apply to flow agents only. They default to 0.2 and 2.0 seconds. max_endpointing_delay must be greater than the wait time. Other agent types ignore both.
minimum_words_before_interruption: 0–10, default 2. minimum_speech_duration_for_interruptions: 0.5–15, default 0.5.

Response envelope

Every v3 response uses the same envelope:

Field	Meaning
`status`	`success` or `error`. Always lowercase.
`message`	A human-readable summary.
`data`	The result. Absent on errors.
`error_details`	A map from field path to message. Present only on some errors.

Fields with no value are omitted rather than returned as null.

A successful create returns 201:

{
  "status": "success",
  "message": "Simple agent created successfully",
  "data": {
    "ai_agent_id": "3f6c2a1e-8b4d-4c9a-9e2f-7d1b5a6c0e42",
    "agent_name": "Support Agent",
    "agent_status": "ACTIVE",
    "operation_type": "CREATE"
  }
}

The full body is in the 201 response example.

Validation errors

Each of these returns 422. message names the block that failed, and error_details names the field.

Request problem	`message`	`error_details` key
`llm.llm_type` missing	`LLM validation failed`	`llm.llm_type`
`llm.llm_id` missing (simple agent)	`LLM validation failed`	`llm.llm_id`
`llm.llm_id` unknown	`LLM model lookup failed`	`llm.llm_id`
LLM model not `ACTIVE`	`LLM model validation failed`	`llm.llm_id`
`stt.model_id` missing	`STT validation failed`	`data.stt.model_id`
`stt.provider_id` unknown	`STT validation failed`	`data.stt.provider_id`
`stt.model_id` not offered by that provider	`STT validation failed`	`data.stt.model_id`
`tts.voice_id` missing	`TTS validation failed`	`data.tts.voice_id`
`llm_type` is `agentic`	`Agent validation failed`	`llm.llm_type`
A field out of range or missing	`Validation failed`	Java property name, for example `vadActivationThreshold` or `agentName`
A field of the wrong type	`Invalid field type in request body`	JSON name, for example `vad_activation_threshold`

Validation failed errors key error_details by the Java property name (vadActivationThreshold). Every other error uses the JSON path (vad_activation_threshold, llm.llm_id). If you map errors to form fields, handle both forms.

POST

ai-agents

curl --request POST \
  --url https://api.example.com/v3/ai-agents \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_name": "Support Agent",
  "language_code": "en-US",
  "speech_speed": 1,
  "vad_activation_threshold": 0.4,
  "welcome_message": "Hi, thanks for calling. How can I help?",
  "llm": {
    "llm_id": "9d259647-d5ec-423d-96a9-2750980e8ecb",
    "llm_type": "simple",
    "model_temperature": 0,
    "system_prompt": "You are a helpful assistant."
  },
  "stt": {
    "provider_id": "6a5c45808d2d94e9d0e255d3",
    "model_id": "aec2493a-eba9-48d0-9e64-4aab4437f7f5"
  },
  "tts": {
    "provider_id": "6a5c079f814b8ed08b15172b",
    "voice_id": "cgSgspJ2msm6clMCkdW9"
  }
}
'

{
  "status": "success",
  "message": "Simple agent created successfully",
  "data": {
    "ai_agent_id": "3f6c2a1e-8b4d-4c9a-9e2f-7d1b5a6c0e42",
    "agent_name": "Support Agent",
    "agent_status": "ACTIVE",
    "language_code": "en-US",
    "llm": {
      "llm_id": "9d259647-d5ec-423d-96a9-2750980e8ecb",
      "llm_type": "simple",
      "model_provider": "openai",
      "model_name": "gpt-4o-mini",
      "model_display_name": "GPT-4o mini",
      "model_temperature": 0,
      "max_tokens": 4096,
      "system_prompt": "You are a helpful assistant."
    },
    "stt": {
      "provider_id": "6a5c45808d2d94e9d0e255d3",
      "provider": "deepgram",
      "model_id": "aec2493a-eba9-48d0-9e64-4aab4437f7f5",
      "model": "nova-3"
    },
    "tts": {
      "provider_id": "6a5c079f814b8ed08b15172b",
      "provider": "elevenlabs",
      "voice_id": "cgSgspJ2msm6clMCkdW9",
      "voice_name": "Jessica",
      "model_name": "eleven_flash_v2_5",
      "voice_temperature": 0.2
    },
    "speech_speed": 1,
    "vad_activation_threshold": 0.4,
    "welcome_message": "Hi, thanks for calling. How can I help?",
    "enable_user_interruptions": true,
    "minimum_speech_duration_for_interruptions": 0.5,
    "minimum_words_before_interruption": 2,
    "interruption_mode": "vad",
    "ambient_sound": "none",
    "ambient_sound_volume": 1,
    "end_call_after_silence_seconds": 10,
    "max_call_duration_seconds": 1800,
    "voicemail_detection_timeout_seconds": 90,
    "agent_ended_call_delay_seconds": 2,
    "welcome_message_delay_in_seconds": 2,
    "enable_amd": false,
    "silence_reminder_enabled": false,
    "silence_reminder_duration_seconds": 10,
    "max_number_of_silence_reminders": 3,
    "interval_between_silence_reminders_seconds": 10,
    "organization_id": "org_7f3a9c",
    "agent_owner_id": "usr_12ab34",
    "created_by_user_id": "usr_12ab34",
    "created_at": "2026-10-15T09:30:12.481Z",
    "modified_at": "2026-10-15T09:30:12.481Z",
    "current_version": 1,
    "operation_type": "CREATE"
  }
}

Body

application/json

stt and tts are required in practice for simple agents — flow agents carry their speech selection inside graph_data.agentDefaults and omit the root objects.

agent_name

string

required

Name of the agent, 2–200 characters.

Required string length: 2 - 200

Example:

"Customer Support Agent"

llm

LlmConfig · object

required

Language model configuration. Select the model by llm_id; see List LLM models.

Show child attributes

language_code

string | null

BCP-47 language code for the agent, for example en-US.

timezone

string | null

Canonical IANA time zone the agent reads its clock in, e.g. 'Asia/Tokyo'. Rejected if it is not a tzdb name: abbreviations (JST), UTC offsets (+09:00) and city-only strings (Tokyo) are not accepted. Omitted or null leaves the agent without a timezone; there is no default.

speech_speed

number | null

default:1

Speaking-rate multiplier for the agent's audio: 1.0 is normal, below 1.0 slower, above 1.0 faster.

Required range: 0.5 <= x <= 2

knowledge_base_id

string | null

Knowledge base the agent retrieves from.

welcome_message

string | null

Custom message the agent speaks when the call begins.

Example:

"Hello! Thanks for calling. How can I help you today?"

welcome_message_delay_in_seconds

number | null

default:2

Delay in seconds, 0–10, before the agent speaks the welcome message.

Required range: 0 <= x <= 10

enable_user_interruptions

boolean | null

default:true

Whether the caller can interrupt the agent while it is speaking.

interruption_mode

enum<string> | null

Interruption detection strategy. Null when unset.

Available options:

vad,

adaptive

minimum_speech_duration_for_interruptions

number | null

default:0.5

Seconds of speech before an interruption is accepted. Minimum 0.5 on create; 0.0 is accepted on update.

Required range: 0.5 <= x <= 15

minimum_words_before_interruption

integer | null

default:2

Minimum number of words, 0–10, the caller must say before the agent treats the speech as an interruption. Used when enable_user_interruptions is true.

Required range: 0 <= x <= 10

vad_activation_threshold

number | null

Voice activity detection sensitivity, 0.10–0.90. There is no service-side default: when unset, the call handler uses its own per-language default, and the key is omitted from create, get and update responses. On update, omitting the key keeps the stored value.

Required range: 0.1 <= x <= 0.9

wait_time_before_detecting_end_of_speech

number | null

Seconds of silence before the caller's turn is treated as finished. Flow agents only: when omitted on create, a flow agent gets 0.2. Other agent types ignore the value: create stores nothing and update keeps whatever was stored.

Required range: 0 <= x <= 15

max_endpointing_delay

number | null

Upper bound, in seconds, on how long end-of-speech detection may wait. Flow agents only: when omitted on create, a flow agent gets 2.0. It must be greater than wait_time_before_detecting_end_of_speech, otherwise the request returns 422. Other agent types ignore the value.

Required range: 0 <= x <= 15

ambient_sound

enum<string> | null

default:none

Background sound mixed into the call audio. none adds no sound.

Available options:

office,

cafe,

restaurant,

park,

street,

home,

library,

airport,

train_station,

beach,

none

ambient_sound_volume

number | null

default:1

Volume of the ambient sound, 0–2, where 1 is normal volume.

Required range: 0 <= x <= 2

enable_noise_cancellation

boolean | null

default:true

Whether to apply noise cancellation to the caller's audio before speech recognition.

webhook_url

string | null

Receives webhook notifications about call events.

end_call_after_silence_seconds

integer | null

default:10

Seconds of caller silence, 10–30, after which the call ends automatically.

Required range: 10 <= x <= 30

max_call_duration_seconds

integer | null

default:1800

Maximum duration of the call in seconds, 30–3600.

Required range: 30 <= x <= 3600

end_call_instruction

string | null

Instruction given to the LLM governing how and when to end the call.

agent_ended_call_delay_seconds

number | null

default:2

Delay in seconds, 0–10, before the call ends when the agent decides to end it.

Required range: 0 <= x <= 10

enable_amd

boolean | null

default:false

Enable answering-machine detection.

amd_voicemail_message

string | null

Played when answering-machine detection identifies a voicemail.

voicemail_detection_timeout_seconds

integer | null

default:90

Seconds to wait for voicemail detection before taking action. Used when enable_amd is true.

Required range: x >= 0

silence_reminder_enabled

boolean | null

default:false

Whether the agent reminds the caller to speak after a period of silence.

silence_reminder_duration_seconds

number | null

default:10

Seconds of silence, 10–30, before the agent reminds the caller to speak. Used when silence_reminder_enabled is true.

Required range: 10 <= x <= 30

max_number_of_silence_reminders

integer | null

default:3

Maximum number of silence reminders, 1–10. Used when silence_reminder_enabled is true.

Required range: 1 <= x <= 10

interval_between_silence_reminders_seconds

number | null

default:10

Seconds between two consecutive silence reminders, 3–30. Used when silence_reminder_enabled is true.

Required range: 3 <= x <= 30

dynamic_data_config

DynamicDataConfigItem · object[] | null

External HTTP sources the agent calls to fetch data during the conversation, for example a customer record. See Dynamic data.

Show child attributes

post_call_analysis

PostCallAnalysisItem · object[] | null

Analysis items to extract from the call after it ends. The type of each item sets the shape of its result. You can also manage these items with the post-call analysis API.

Show child attributes

Example:

[
  {
    "type": "string",
    "name": "call_summary",
    "description": "A short summary of the call.",
    "system_prompt": "Summarize the call in two sentences.",
    "examples": [
      "The caller asked about a late delivery and was given a new date."
    ]
  },
  {
    "type": "enum",
    "name": "customer_sentiment",
    "description": "Overall sentiment of the caller.",
    "system_prompt": "Classify the caller's overall sentiment.",
    "choices": ["positive", "neutral", "negative"]
  }
]

pronunciations

Pronunciation · object[] | null

Pronunciation overrides: the agent speaks each term as its replacement. Applied to simple agents only. Entries are stored as sent, without validation.

Show child attributes

stt

SttConfig · object

Speech-to-text configuration. Select the provider and model by id; see List STT providers. Required for simple agents; ignored for flow agents.

Show child attributes

tts

TtsConfig · object

Text-to-speech configuration. Select the provider and voice by id; see List TTS providers. Required for simple agents; ignored for flow agents.

Show child attributes

agent_status

enum<string> | null

default:ACTIVE

Lifecycle status of the new agent.

Available options:

ACTIVE,

INACTIVE

template_id

string | null

Template to seed the agent from.

Response

Agent created

Standard v3 envelope. error_details is present only on failures; null fields are omitted.

status

enum<string>

Outcome of the request: success or error, in lowercase.

Available options:

success,

error

message

string

Human-readable message about the result.

data

AIAgentV3Response · object

The agent. Omitted on errors.

Show child attributes

error_details

Error Details · object | null

Field path to message, for validation failures. Omitted when there are none.

Show child attributes

API Reference

AI Agents v3

AI Agents v2

LLM Models

Speech Providers

Built-in Tools

Custom Tools

Calls

Call Recording

Post-call Analysis

Phone Numbers

Knowledge Bases

Prompt Generation

Public Sharing

Webhook Subscriptions

API Keys

Create AI Agent

References, not inline configuration

Agent types

Field notes

Response envelope

Validation errors

Body

Response