Skip to main content
POST
Create Agent

Authorizations

Authorization
string
header
required

Your API key sent as a Bearer credential — Authorization: Bearer <api_key>, where <api_key> starts with oi_sk_ (create one via POST /v1/api-keys). Although the field is labelled 'token', paste your API key here. A dashboard JWT is also accepted on this header for the same endpoints.

Body

application/json
name
string
required
Required string length: 1 - 255
llm_id
string<uuid> | null

UUID of an LLM model from GET /v1/llm-models. Omit to use the platform-default LLM (OpenAI gpt-4o-mini) so a new user can create an agent with just name and start a web call.

webhook_id
string<uuid> | null
transcriber
TranscriberConfig · object
tts
TTSConfig · object
first_message
string | null
end_call_phrases
string[]
max_duration_seconds
integer
default:600
Required range: 30 <= x <= 7200
interruption_sensitivity
number
default:0.5
Required range: 0 <= x <= 1
silence_timeout_seconds
integer
default:10
Required range: 1 <= x <= 300
enable_recording
boolean
default:false
language
string
default:en
Required string length: 2 - 8
dynamic_variables
Dynamic Variables · object

Template variables interpolated into system_prompt and first_message. Use {{var_name}} placeholders (legacy single-brace {var_name} also works). Per-call variables override these at dispatch time.

voicemail_detection
boolean
default:false
voicemail_message
string | null
responsiveness
number
default:0.5

0=patient, 1=snappy. Maps to worker min_endpointing_delay.

Required range: 0 <= x <= 1
speed
number
default:1

Top-level speech rate. Overrides tts.speed at the worker when non-default.

Required range: 0.5 <= x <= 2
background_sound
string | null

None, 'office', 'cafe', etc. Store-only this iteration.

Maximum string length: 64
emotions
boolean
default:false
job_description
string | null

Free-form role context. Prepended to system_prompt at the worker.

metadata
Metadata · object

Response

Successful Response

id
string
required
name
string
required
llm_id
string
required
webhook_id
string | null
required
transcriber
Transcriber · object
required
tts
Tts · object
required
first_message
string | null
required
end_call_phrases
string[]
required
max_duration_seconds
integer
required
interruption_sensitivity
number
required
silence_timeout_seconds
integer
required
enable_recording
boolean
required
language
string
required
dynamic_variables
Dynamic Variables · object
required
voicemail_detection
boolean
required
voicemail_message
string | null
required
responsiveness
number
required
speed
number
required
background_sound
string | null
required
emotions
boolean
required
job_description
string | null
required
metadata
Metadata · object
required
created_at
string<date-time>
required
updated_at
string<date-time>
required
effective_system_prompt
string | null

Read-only. The system prompt the agent is actually given at call time: the linked LLM model's system_prompt with job_description prepended as a # Role block — exactly as the worker assembles it. Per-call dynamic-variable interpolation and knowledge-base chunks are resolved at runtime and not reflected here. Populated on GET /v1/agents/{id}; null on list responses.