Build agents with the API
Create, configure, publish, test and run voice agents with the CallMitra API.
An agent is the voice AI that talks on your calls. It holds the script, the knowledge, the voice, the language and the call rules. This guide shows how to build one end to end with the API.
| Step | Endpoint |
|---|---|
| List agents | GET /api/v1/agents/ |
| Create an agent | POST /api/v1/agents/ |
| Import from another platform | POST /api/v1/agents/import |
| Read one agent | GET /api/v1/agents/{agent_id} |
| Save draft changes | PATCH /api/v1/agents/{agent_id} |
| Publish the draft | POST /api/v1/agents/{agent_id}/publish |
| Start taking calls | POST /api/v1/agents/{agent_id}/go-live |
| Stop taking calls | POST /api/v1/agents/{agent_id}/pause |
| Place a test call | POST /api/v1/agents/{agent_id}/test-call |
| Set the post-call webhook | PUT /api/v1/agents/{agent_id}/post-call-webhook |
| Delete an agent | DELETE /api/v1/agents/{agent_id} |
| List voices | GET /api/v1/voices/ |
| List tools | GET /api/v1/tools/ |
All agent endpoints need an API key with the Agents resource (Authentication). A read-only key can list and read agents, but cannot create or change them.
Versions and lifecycle
Every agent has two copies of its settings:
configis the published version. Live calls, campaigns and test calls use it.draftConfigis the working copy.PATCHwrites here. When there is no pending draft,draftConfigequalsconfig.
unpublishedChanges is true while a draft is waiting to be published. Secrets inside the config (such as webhook signing secrets) are never returned.
Three fields describe where the agent is:
| Field | Values | Meaning |
|---|---|---|
status | draft, published, archived | draft until the first publish. |
takingCalls | true, false | Set by go-live and pause. |
rosterState | see below | One badge that combines the two, plus whether a number is assigned. |
rosterState | When |
|---|---|
in_training | The agent has never been published. |
paused | Published, but takingCalls is false. |
ready | Taking calls, but no phone number is assigned. |
live | Published, taking calls, and a phone number is assigned. |
archived | The agent is archived. |
The usual flow is:
Create the agent. It starts as a draft (rosterState is in_training).
Edit it with PATCH. Each change lands in draftConfig.
Publish it. The draft becomes config.
Test it with a test call to your own phone.
Go live once a phone number is assigned. Pause it to stop new calls.
Create an agent
Send a name and a config. Every field is optional, so {} creates an empty draft with default settings. In practice you send at least a language, a voice, a system prompt and a greeting:
curl -X POST https://api.callmitra.ai/api/v1/agents/ \
-H "X-API-Key: $CALLMITRA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: create-agent-priya-001" \
-d '{
"name": "Priya",
"config": {
"language": "hi-IN",
"stt": "sarvam",
"tts": "sarvam",
"voice": "priya",
"llm_model": "gpt-4o-mini",
"template_payload": {
"system_prompt": "You are Priya from Acme Realty. Qualify the lead'\''s budget and preferred area.",
"greeting_message": "Namaste, main Acme Realty se Priya bol rahi hoon."
}
}
}'The response holds the new agent (shortened here):
{
"success": true,
"agent": {
"id": "3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10",
"name": "Priya",
"status": "draft",
"rosterState": "in_training",
"takingCalls": false,
"unpublishedChanges": false,
"language": "hi-IN",
"config": {
"language": "hi-IN",
"llm_model": "gpt-4o-mini",
"tts": "sarvam",
"voice": "priya"
}
}
}Body fields:
| Field | Type | Default | Notes |
|---|---|---|---|
name | string | "" | Display name, up to 255 characters. |
config | object | defaults | The agent settings. See Config reference. |
status | draft or published | draft | Send published to publish on create. The language model check then runs too. |
sourceTemplateId, sourceTemplateSlug, sourceTemplateVersion | string / integer | none | Optional record of the template you started from. |
On create and update, CallMitra checks that:
configis at most 512 KB as JSON (UTF-8) and nested at most 16 levels deep. A bigger config returns413payload_too_large; a deeper one returns422parameter_invalid;- every value is the right type and within its range or list of choices;
config.languageis an active language;config.sttis a speech-to-text provider that is available;config.voiceexists for theconfig.ttsprovider and supportsconfig.language;- every tool URL (
base_url,url,server_url,endpoint, or an absolutepath) andpost_call_webhook.urlis a publichttp(s)address. Private, internal and loopback addresses are refused at save time; - every
tools[].config.tool_idis a tool in your workspace; - the language model is ready to use (only when
statusispublished, or when you publish).
A failed check returns 422 parameter_invalid, with param set to the config path, for example config.voice or config.tools.0.config.base_url. If your plan has no room for another agent, you get payment_required.
createAgent accepts an Idempotency-Key header, so a retry does not create a second agent (Idempotency).
Config reference
Config keys are snake_case by design, unlike the camelCase used in the rest of the API. config uses the same shape CallMitra stores, and agent import produces that shape too, so the keys stay as they are. The tables list the fields the API accepts, with types, defaults and allowed values.
Unknown keys are dropped, not refused
A config key CallMitra does not know is ignored and not stored. You do not get an error for it. Check the spelling of every key, and read the agent back to confirm what was saved. Only a known key with a bad value returns 422.
Script and knowledge
| Field | Type | Default | Notes |
|---|---|---|---|
template_payload.system_prompt | string | "" | The instructions the agent follows. |
template_payload.greeting_message | string | "" | The first thing the agent says. |
template_payload.knowledge_base | string | "" | Free-text knowledge. |
system_prompt | string | — | Write shortcut. Fills template_payload.system_prompt only when that is empty. |
greeting_message | string | — | Write shortcut. Fills template_payload.greeting_message only when that is empty. |
script.opening | string | "" | Structured script: how the call opens. |
script.goal | string | "" | What the call should achieve. |
script.steps | array of {name, instruction} | [] | Ordered call steps. |
script.end_rules | array of strings | [] | When to end the call. |
script.closing | string | "" | How the call closes. |
script.strictness | flexible, balanced, strict | balanced | How closely the agent follows the steps. |
script.ask_first_question_in_greeting | boolean | — | Ask the first question in the greeting. |
knowledge.details | array of {key, label, value} | [] | Business facts, such as hours or address. |
knowledge.items | array of {kind, q, text} | [] | kind is fact, qa, rule or objection. |
knowledge.notes | string | "" | Extra notes. |
agent_mode | announcement, awareness, conversation, ivr_survey, survey | conversation | The kind of call. |
job_role | string | "" | Up to 200 characters. |
success_criteria | string | "" | What a successful call looks like. Up to 4,000 characters. |
required_fields | array of {key, label, type} | [] | Data to collect on the call. Up to 32. type is string, number, email, phone, date or bool. |
The script and knowledge together can hold up to 48,000 characters. Older agents that use only a system prompt can hold up to 40,000. Over the limit, saving and publishing fail with agent_state_blocked.
Voice
| Field | Type | Default | Notes |
|---|---|---|---|
tts | string | sarvam | Text-to-speech provider. Use a provider value from listVoices. |
voice | string | "" | A voiceId from listVoices for the tts provider. |
agent_gender | female, male, any | any | |
tone | string | natural | |
caller_name | string | "" | The name the agent uses. Up to 120 characters. |
tts_speed | number | 1.0 | From 0.5 to 1.5. |
tts_volume | number | 1.0 | From 0.2 to 1.0. |
background_sound.enabled | boolean | false | Play a background sound. |
background_sound.preset | string | off | Sound name, for example office. |
background_sound.volume | number | 0.5 | From 0.02 to 1.0. |
Language and speech-to-text
| Field | Type | Default | Notes |
|---|---|---|---|
language | string | en-IN | Main language. Must be an active language from listVoices languages. |
extra_language | string | "" | A second language. |
auto_adapt_language | boolean | false | Switch language to match the caller. |
stt | deepgram, openai, sarvam, soniox | deepgram | Speech-to-text provider. |
noise_reduction | off, standard, strong | standard |
Language model
| Field | Type | Default | Notes |
|---|---|---|---|
llm_model | string | gpt-4o-mini | The model that writes replies. |
temperature | number | 0.55 | From 0 to 2. |
max_tokens | integer | 250 | From 1 to 32000. Longest reply per turn. |
reasoning_effort | none, minimal, low, medium, high, xhigh, max | minimal | For reasoning models. |
voice_engine | pipeline, gemini_live, openai_realtime, elevenlabs_agents | pipeline | pipeline chains speech-to-text, the model and text-to-speech. |
realtime_model, realtime_voice | string | — | Used with a realtime voice_engine. |
Turn-taking
| Field | Type | Default | Notes |
|---|---|---|---|
interrupt_mode | time, words | time | How the caller interrupts the agent. |
interrupt_min_speech_ms | integer | 220 | From 100 to 2000. Speech needed to interrupt, in time mode. |
interrupt_word_count | integer | 2 | From 1 to 3. Words needed to interrupt, in words mode. |
interruption_sensitivity | low, medium, high | medium | |
conversation_engine | v1, v2 | v1 |
Compliance
| Field | Type | Default | Notes |
|---|---|---|---|
ai_disclosure | boolean | true | The agent says it is an AI. |
recording_notice | boolean | true | The agent says the call is recorded. |
call_recording | boolean | true | Record the call. |
Limits and calling
| Field | Type | Default | Notes |
|---|---|---|---|
call_time_limit_seconds | integer | 600 | From 10 to 3600. The call ends at this limit. |
calling_mode | "", instant, bulk | "" |
Inline tools
| Field | Type | Default | Notes |
|---|---|---|---|
tools | array | [] | Inline tools. Up to 32. See Tools. |
tools[].kind | string | — | end_call, transfer_call, api_request, function, mcp, lookup_open_tickets, create_ticket, add_ticket_note, schedule_callback or send_whatsapp. |
tools[].name | string | — | Up to 128 characters. |
tools[].description | string | — | Up to 2,000 characters. Tells the model when to use the tool. |
tools[].enabled | boolean | true | |
tools[].config | object | {} | Kind-specific settings. For example {"phone_number": "+919800000000"} for transfer_call, or {"base_url": "https://api.example.com", "path": "/orders", "method": "POST"} for api_request. |
For an inline api_request tool, the host and method always come from the saved config:
base_urlmust be a publichttp(s)address. An absolutepathis used as the base only whenbase_urlis empty.- During a call, the model may only add a relative path under
base_url, plus a JSON body. A path with a scheme,//,..segments, encoded slashes or control characters is refused. methodisGET,POST,PUT,PATCHorDELETE. The default isPOST.- Requests go only to public addresses and do not follow redirects.
Post-call
| Field | Type | Notes |
|---|---|---|
post_call_webhook | object {url, trigger} | Prefer the post-call webhook endpoint. It applies at once and stores the signing secret safely. |
Pick a voice
GET /api/v1/voices/ lists the voices, providers and languages you can use. Filter with provider and language:
curl "https://api.callmitra.ai/api/v1/voices/?provider=sarvam&language=hi-IN" \
-H "X-API-Key: $CALLMITRA_API_KEY"The response has three lists. The filters narrow voices only:
{
"success": true,
"providers": [
{ "id": "sarvam", "name": "Sarvam", "count": 12, "previewSupported": true }
],
"voices": [
{
"provider": "sarvam",
"providerName": "Sarvam",
"voiceId": "priya",
"name": "Priya",
"gender": "female",
"languageCodes": ["hi-IN", "en-IN"],
"sortOrder": 1,
"previewSupported": true
}
],
"languages": [{ "id": "hi-IN", "name": "Hindi" }]
}Copy three values into the config:
config.tts= the voice'sprovider;config.voice= itsvoiceId;config.language= a languageidthat appears in the voice'slanguageCodes.
If the voice does not exist for that provider, or does not support the language, create and update return 422 parameter_invalid with param config.voice.
Update an agent
PATCH /api/v1/agents/{agent_id} takes name and config, both optional.
- Config changes go to the draft.
config(the published version) does not change until you publish. Live calls keep using the published version. - Only the top-level keys you send change. Keys you leave out keep their draft values.
- Nested objects are replaced, not merged. If you send
script, send the wholescriptobject. Anyscriptfield you leave out is cleared. nameapplies at once. It changes the display name immediately and also setscaller_namein the draft.
curl -X PATCH https://api.callmitra.ai/api/v1/agents/3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10 \
-H "X-API-Key: $CALLMITRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "config": { "tts_speed": 1.1, "call_time_limit_seconds": 300 } }'After this call, unpublishedChanges is true and draftConfig holds the new values.
PATCH returns:
parameter_invalidfor a bad value, voice or language;agent_state_blockedwhen the script and knowledge are over the size limit, when the text uses an unknown@token, or when a webhook orapi_requesttool URL is not a public address.
Publish
POST /api/v1/agents/{agent_id}/publish copies the draft into config, clears the draft and sets status to published. It takes no body.
curl -X POST https://api.callmitra.ai/api/v1/agents/3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10/publish \
-H "X-API-Key: $CALLMITRA_API_KEY"Before it publishes, CallMitra checks the content size limit, @ tokens, public URLs, the voice, and that the language model is ready. If a check fails, nothing is published and you get 422 agent_state_blocked. The message says what to fix.
Publishing does not change takingCalls. A live agent stays live and starts using the new version.
Go live and pause
POST /api/v1/agents/{agent_id}/go-live sets takingCalls to true.
- The agent needs a phone number assigned. Assign numbers in the console. You can see them in
assignedPhoneNumbersand with listPhoneNumbers. - An archived agent cannot go live.
- If the agent has never been published, or has a pending draft, go-live publishes the draft first. The same publish checks run.
If go-live is refused, you get agent_state_blocked.
POST /api/v1/agents/{agent_id}/pause sets takingCalls to false. The settings and the published version stay as they are. Call go-live again to resume.
Test call
POST /api/v1/agents/{agent_id}/test-call calls a phone you choose, using one of your numbers as caller ID.
| Field | Type | Required | Notes |
|---|---|---|---|
phoneNumberId | string | yes | The ID of one of your phone numbers, from listPhoneNumbers. |
destination | string | yes | The phone to call. E.164 (+919812345678) or a local number. |
dynamicValues | object | no | Values for placeholders in the script, for example {"customer_name": "Asha"}. |
curl -X POST https://api.callmitra.ai/api/v1/agents/3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10/test-call \
-H "X-API-Key: $CALLMITRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phoneNumberId": "8d1e4b2a-0c3f-4a5e-9b7d-6f2a1c3e5d70",
"destination": "+919812345678",
"dynamicValues": { "customer_name": "Asha" }
}'{
"success": true,
"callId": "c2b7e9d4-1a3f-4e6b-8c5d-7f9a0b1c2d3e",
"phoneNumber": "+919812345678",
"message": "Test call initiated"
}Read the result with getCall using callId.
Test calls use the published version
A test call runs config, not draftConfig. Publish your changes before you test them.
Test calls are not billed. Free plans have a cap on test calls. Errors:
| Code | When |
|---|---|
resource_not_found | phoneNumberId is not one of your numbers (param is phoneNumberId). |
agent_test_call_failed | The call could not be placed, for example the free test-call cap is reached or the carrier refused it. |
payment_required | Your plan does not include this. |
Post-call webhook
PUT /api/v1/agents/{agent_id}/post-call-webhook sets where CallMitra posts the result after each call this agent handles. It applies to the live agent at once, with no publish needed. A key with the Agents or Webhooks resource can call it.
| Field | Type | Default | Notes |
|---|---|---|---|
url | string | — | A public address, up to 2,000 characters. Send "" to remove the webhook. |
secret | string | — | Signing secret, up to 500 characters. Leave it out to keep the current secret. |
trigger | every, completed, voicemail | every | Which calls send the webhook. |
curl -X PUT https://api.callmitra.ai/api/v1/agents/3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10/post-call-webhook \
-H "X-API-Key: $CALLMITRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://example.com/hooks/callmitra", "secret": "whsec_example", "trigger": "completed" }'The response holds the agent and webhook: {url, trigger, hasSecret}. The secret itself is never returned. A campaign that has its own webhook uses that one instead. A URL that is not a public address returns agent_state_blocked.
For the payload and signature, see Per-agent webhooks. For workspace-wide events, see Webhooks.
Tools
Tools let the agent act during a call: end it, transfer it, call your API, create a ticket, and more.
- Inline tools live in
config.tools. Add, change or remove them withPATCH, then publish. See Inline tools in the config reference. The end-call tool is added for you. - Workspace tools are shared tools you build in the console. The API can read them with listTools and getTool, but cannot create them or attach them to an agent. Do both in the console.
A tool's credentials are never returned. authSecretSet tells you whether one is stored. An unknown tool ID returns tool_not_found.
Delete an agent
DELETE /api/v1/agents/{agent_id} removes the agent permanently.
- Past calls keep their records.
- Campaigns that used the agent lose it. Starting such a campaign fails with
campaign_has_no_agentuntil you set a new agent.
To stop an agent without losing it, pause it instead.
Errors
Errors use the standard envelope (Errors):
{
"detail": "config.tts_speed must be a number from 0.5 to 1.5",
"error": {
"type": "invalid_request_error",
"code": "parameter_invalid",
"message": "config.tts_speed must be a number from 0.5 to 1.5",
"param": "config.tts_speed",
"docUrl": "https://docs.callmitra.ai/errors/parameter_invalid",
"requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69"
}
}| Code | Status | When |
|---|---|---|
parameter_invalid | 422 | A config value is the wrong type or out of range; the voice, language or speech-to-text provider is not available; a tool or webhook URL is not public; or a tool_id is not in your workspace. |
payload_too_large | 413 | config is larger than 512 KB. |
agent_state_blocked | 422 | Publish or go-live is refused, content is over the limit, or a URL is not public. |
agent_not_found | 404 | The agent ID does not exist in this workspace. |
agent_test_call_failed | 400 | The test call could not be placed. |
tool_not_found | 404 | The tool ID does not exist. |
payment_required | 402 | Your plan's agent limit is reached, or the feature is not in your plan. |
permission_denied | 403 | The key cannot write agents. |
Related
- Import agents from Vapi, Retell or Bland
- Run campaigns with your agent
- Per-agent webhooks
- Idempotency
- Errors