Skip to main content
When you create or update an agent, you send a JSON body to POST /api/v1/agents or PUT /api/v1/agents/{agent_id}. This page covers every field you can include. Required fields are title and questions.

​
Top-level fields

​
string
required
The display name for the agent. Shown in the dashboard and in conversation records.
​
array of Question
required
The questions the agent asks, in order. See Question Types for the structure of each question object.
​
array of Branch
default:"[]"
Conditional question groups. Declare a branch here, then tag individual questions with its id using branch_id. See Branching for the full setup.
​
string
An optional internal description for your own reference. Not used by the voice agent.
​
string
Extra instructions appended to the agent’s system prompt. Use this to give the agent domain context, rules about how to handle edge cases, or persona reinforcement beyond agent_persona.
​
string
A description of the agent’s character. For example: "You are a friendly and professional healthcare coordinator named Priya."
​
string
A description of the expected caller. Helps the agent calibrate its tone and vocabulary. For example: "The caller is a patient who has recently been discharged from hospital."
​
string
The language code for the agent’s speech output. Uses BCP 47 language tags (e.g., "en-IN", "hi-IN"). Defaults to the workspace language if omitted.
​
boolean
default:"true"
When true, the agent opens the conversation with its intro script or a generated greeting. Set to false if your telephony infrastructure plays an IVR prompt before connecting the agent.
​
boolean
default:"true"
When true, the agent asks exactly one question, waits for an answer, then moves on. When false, the agent may batch multiple questions into a single turn.
​
boolean
default:"false"
When true, the caller’s audio input is suppressed while the agent is speaking. Useful in noisy environments where background sound triggers false end-of-turn detection.
​
boolean
default:"true"
When true, the agent interjects short acknowledgements ("mm-hmm", "I see") while the caller is speaking to signal it is listening.
​
"fixed" | "llm"
default:"\"fixed\""
Controls how acknowledgement phrases are chosen. "fixed" cycles through hearing_acknowledgement_phrases. "llm" generates a contextually appropriate phrase each time.
​
array of strings
Custom phrases used in "fixed" acknowledgement mode. If omitted, a built-in default list is used. Example: ["Got it", "Understood", "Okay"].
​
Scripts object
Exact words for the opening and closing of the call. See Scripts below.
​
string
Only valid on POST /api/v1/agents (create). Associates the agent with a specific workspace. Omit to place the agent in your personal workspace.

​
Scripts

The scripts object controls what the agent says at the start and end of every call. Each field is optional — the agent improvises if you leave it out.
​
string
The exact words the agent speaks to open the conversation. If omitted, the agent generates an appropriate greeting based on its persona and the first question.
​
string
The closing words the agent speaks after all questions have been answered successfully.
​
string
The closing words the agent speaks when the call ends without completing all questions — for example, when the caller hangs up early or a required question exhausts its retries.
You cannot set outro_incomplete without also setting outro. If you include outro_incomplete in the request but omit outro, the save will be rejected with a 400 validation error.

​
Reading the agent back

When you read an agent back via GET /api/v1/agents/{agent_id}, some field names differ from the ones you used to create it. The stored format uses a different vocabulary: To write to an agent using the stored format directly — for example, when round-tripping a config you fetched from GET — use PUT /api/v1/agents/{agent_id}/config instead of the standard PUT /api/v1/agents/{agent_id}.
If your save is rejected, the response is a 400 with a validation_issues array. Each item in the array has a field property identifying which field failed and a message property explaining why. Fix all reported issues and resubmit — no partial saves are applied.