Create Agent
Create a new AI voice agent on the v1 API.
/v1 API reference and is the supported path for new integrations. See the migration guide for versioning guidance.When to use this
Use this endpoint to create agents programmatically as part of an onboarding flow, template system, or multi-tenant setup. The request is scoped to the authenticated organization automatically.Before you begin
Fetch alanguage_id from List Languages and a voice_id from List Voices. Creating an agent does not publish its first version.
Minimal request
Start with the four required fields. Add advanced speech, model, fallback, analysis, routing, and function settings only when the basic agent works:Fallback STT And Post-Call Analysis
Usefallback_stt_enabled and stt_fallback_transcriber_id to configure fallback transcription on the first draft version. Pick the fallback transcriber ID from List Fallback Transcribers.
If you need post-call fields at creation time, pass post_call_analysis. To change the LLM used for extracting those fields after creation, use Update Agent with post_call_analysis_llm_id.
Phone Numbers And Predictive Preprocessing
You can includeinbound_phone_number_id and outbound_phone_number_id when creating the first draft version. The IDs must belong to the authenticated workspace. Creating the agent stores those IDs on the draft, but live dispatch routing is claimed only when the version is published through Update Agent with is_published: true.
Use predictive_preprocessing_enabled to turn on predictive preprocessing for the first draft version when your agent should pre-generate likely next replies between turns. This setting is most useful for cascaded agents with repeated, predictable scripts.
/agents2 endpoint uses a separate, documentation-specific body (CreateAgents2BodyDto). If you are migrating from /agents2, do not assume the bodies are identical - review the request schema for /v1/agents in the panel on this page.Verify the result
Store the returnedid, confirm current_version.version_number is 1, then publish the draft with version_number: 1 and is_published: true before placing a call.
If the create request times out, list agents and search for the title before retrying. The contract does not currently publish an idempotency key.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Title of the agent (max 70 characters)
70"Customer Support Agent"
ID of the language the agent speaks
"1"
ID of the voice used by the agent
"VOICE123456789"
Prompt text used by the agent
"Hello, how can I assist you today?"
Indicates whether voicemail detection is enabled
true
Hang up immediately when voicemail is detected instead of leaving a message
false
Message played when voicemail is detected (only used when hangup_on_voicemail is false)
"Hi, please call us back at your convenience."
Whether the agent listens for keypad (DTMF) input from the caller
true
Seconds to wait for keypad input before timing out (0-15)
0 <= x <= 155
Single character key that ends the call (digits, * or #)
"#"
Maximum number of DTMF digits to collect from the caller (1-50)
1 <= x <= 501
Seconds of silence after which the call is automatically ended (0-1800)
0 <= x <= 1800180
Maximum call duration in seconds before the call is forcibly ended
x >= 0600
Seconds of silence inserted before the agent starts speaking
x >= 00
How long to let the phone ring before treating the call as unanswered (seconds)
x >= 130
Background sound file or identifier
Volume of background sound (0 to 2)
0 <= x <= 2Enable or disable ambient noise playback on the call
Responsiveness level from 0 to 1.
0 <= x <= 1Interruption sensitivity level (0 to 1)
0 <= x <= 1How eagerly the agent responds (0 to 1). Only applied when transcriber is Soniox.
0 <= x <= 1Enable or disable backchanneling
Backchannel frequency from (0 to 1)
0 <= x <= 1Mode for transcription
optimize_for_speed, optimize_for_accuracy Mode for denoising audio input
remove_noise, remove_noise_and_speech Enable or disable speech normalization
Enable or disable transcript formatting
Comma-separated list of backchannel keywords
Comma-separated list of boosted keywords
Interval between reminder messages (in seconds)
Frequency of reminder messages
ID of the transcriber catalog entry
Enable parallel fallback STT for this agent
Fallback STT transcriber catalog entry
Milliseconds to wait for primary STT after fallback finalizes first
x >= 0Enable TTS audio caching for this agent
ID of the folder this agent belongs to
"fld_abc123xyz789"
Type of the agent
Single_Prompt_Agent, Conversational_Flow_Agent "Single_Prompt_Agent"
Pipeline subtype for Single_Prompt_Agent. Cascaded = ASR→LLM→TTS pipeline. Speech_To_Speech = direct speech model. Null for Conversational_Flow_Agent.
Cascaded, Speech_To_Speech "Cascaded"
Version title (optional, will be auto-generated if not provided, max 35 characters)
35null
Description of the agent
"This agent handles customer support inquiries"
Timezone for the agent
"Asia/Kolkata"
ID of the outbound phone number to use for this agent. Must be an existing phone number ID in your organization. Stored on the draft at creation; live outbound routing is claimed when the version is published.
ID of the inbound phone number to use for this agent. Must be an existing phone number ID in your organization. Stored on the draft at creation; live inbound routing is claimed when the version is published.
ID of the LLM associated with the agent
"A1B2C3D4E5F6G7"
ID of the webhook associated with the agent
"wh_12345678901234"
System prompt text for the agent
"You are a helpful customer support agent named Sarah."
Node positions for Conversational_Flow_Agent type (stored as JSON string)
"{\"node1\": {\"x\": 100, \"y\": 200}}"
Who starts the conversation
user, agent_dynamic, agent_defined "user"
Welcome message for the agent
"Welcome to our service!"
Whether the agent allows interruptions
true
Instructions for JSON output
IDs of the knowledge bases attached to this agent version
Maximum number of RAG chunks to fetch (1-10)
1 <= x <= 105
Minimum similarity score threshold for RAG results (0-1)
0 <= x <= 10.5
Default values for dynamic variables used in templates
Voice model ID to use for the agent
"voice_model_abc123"
Voice speed (0.25 to 4.0)
0.25 <= x <= 41
Voice temperature (0.0 to 2.0)
0 <= x <= 21
Voice volume (0 to 10)
0 <= x <= 101
Pitch adjustment of the voice (-1 to 1)
-1 <= x <= 10
LLM temperature (0.0 to 2.0)
0 <= x <= 20.1
Opt out of sensitive data storage
false
Opt in to secure URLs
false
Enable fallback LLM for this agent
false
Enable predictive preprocessing for this agent version
false
Milliseconds to wait before triggering the fallback LLM
500
ID (llms.id) of the LLM to use as fallback
"abc123xyz789ab"
Fallback voices for TTS. Used when the primary voice is unavailable.
Functions the agent can invoke during a call (e.g. end call, transfer, booking). Passed at create time; use PATCH to replace later.
Fields to extract from the call transcript after the call ends.
Alias for post_call_analysis (backward compatibility).
Agent identity (required for Conversational_Flow_Agent type on update)
"You are a helpful customer support agent named Sarah."
Agent background (required for Conversational_Flow_Agent type on update)
"You have 5 years of experience in customer support and specialize in helping customers with technical issues."
Response
Agent created successfully.
Signed agent ID
"agent_2g7Xy3tY53gRlp"
Single_Prompt_Agent, Conversational_Flow_Agent Cascaded, Speech_To_Speech