Create agent
Creates an agent. Nothing is dialled and nothing is charged.
name, system_prompt, first_message and language are required. Everything else has a working default, and the response shows every default it filled in. {{name}}-style placeholders in the prompts are filled from each call’s variables.
voice.voice_id must be a voice that GET /v2/voices lists. Anything else is a 400 that names the voices you can use. secondary_languages are other languages your callers may switch to; speech recognition listens for them too.
Turn on the Idempotency-Key header to make retries safe. Sending the same key again returns the agent it first created (200, with Idempotent-Replay: true) instead of a second agent. The same key with a different body is a 409.
Authorizations
Your workspace secret key, sk_live_ followed by 32 hex characters. Create one in the console under Developers.
Headers
Up to 255 characters. The same key within 24 hours replays the first answer and creates nothing new. Build it from your own record, such as order-8842-reminder-1.
255Body
- Option 1
- Option 2
5001112000Replace the whole analysis block. Omit output_schema to remove structured extraction. Requires enabled=true to run.
Archive to block new calls; false restores availability subject to draft validation. Accepted call snapshots remain unchanged.
off, office How the agent takes turns with the caller. Unlike other nested blocks, PATCH merges it field by field: omitted fields keep their current value and {} changes nothing. null resets it to the defaults (interruptions normal, adaptive_interruptions true).
The phone number this agent's outbound calls ring from when the call, or its campaign, does not choose one. Resolution is fixed: the call's (or campaign's) phone_number_id, else this, else the Mirai shared line. A number set here dials through its own provider connection (India destinations only) and is re-checked before every call: if it can no longer call, calls fail with 409 not_ready and campaigns pause, never falling back to the shared line. null unsets it. Kept across a rollback.
Drafts may have empty prompt or greeting, but cannot run calls.
Send call.processed when this agent has post-call tools, analysis or a flow (a flow agent's event carries the call's flow outcome). Set false to turn the event off.
Optional node graph; makes this a flow agent. PATCH replaces the whole graph; null removes it.
Replace the entire input declaration. Null removes it and restores legacy string variables.
30 <= x <= 1800Other languages callers may speak. Speech recognition listens for them as well as the primary language. Optional; the primary language is never repeated here. Entries are reduced to their base code (gu-IN is saved as gu; or is accepted for od), duplicates and the primary language are dropped, and at most 4 remain.
4hi, en, gu, mr, bn, ta, te, kn, ml, pa, od At most 40 tools: 10 pre_call, 20 on_call, 10 post_call. A PATCH replaces the whole list; null empties it. To edit one tool, use PUT/DELETE /v2/agents/{id}/tools/{name}.
40When omitted on create, voice_id defaults to neha. Supplied blocks must include voice_id.
Response
Created