Skip to Content
CallMitraDocs

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.

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:

  • config is the published version. Live calls, campaigns and test calls use it.
  • draftConfig is the working copy. PATCH writes here. When there is no pending draft, draftConfig equals config.

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:

FieldValuesMeaning
statusdraft, published, archiveddraft until the first publish.
takingCallstrue, falseSet by go-live and pause.
rosterStatesee belowOne badge that combines the two, plus whether a number is assigned.
rosterStateWhen
in_trainingThe agent has never been published.
pausedPublished, but takingCalls is false.
readyTaking calls, but no phone number is assigned.
livePublished, taking calls, and a phone number is assigned.
archivedThe 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:

FieldTypeDefaultNotes
namestring""Display name, up to 255 characters.
configobjectdefaultsThe agent settings. See Config reference.
statusdraft or publisheddraftSend published to publish on create. The language model check then runs too.
sourceTemplateId, sourceTemplateSlug, sourceTemplateVersionstring / integernoneOptional record of the template you started from.

On create and update, CallMitra checks that:

  • config is at most 512 KB as JSON (UTF-8) and nested at most 16 levels deep. A bigger config returns 413 payload_too_large; a deeper one returns 422 parameter_invalid;
  • every value is the right type and within its range or list of choices;
  • config.language is an active language;
  • config.stt is a speech-to-text provider that is available;
  • config.voice exists for the config.tts provider and supports config.language;
  • every tool URL (base_url, url, server_url, endpoint, or an absolute path) and post_call_webhook.url is a public http(s) address. Private, internal and loopback addresses are refused at save time;
  • every tools[].config.tool_id is a tool in your workspace;
  • the language model is ready to use (only when status is published, 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

FieldTypeDefaultNotes
template_payload.system_promptstring""The instructions the agent follows.
template_payload.greeting_messagestring""The first thing the agent says.
template_payload.knowledge_basestring""Free-text knowledge.
system_promptstring—Write shortcut. Fills template_payload.system_prompt only when that is empty.
greeting_messagestring—Write shortcut. Fills template_payload.greeting_message only when that is empty.
script.openingstring""Structured script: how the call opens.
script.goalstring""What the call should achieve.
script.stepsarray of {name, instruction}[]Ordered call steps.
script.end_rulesarray of strings[]When to end the call.
script.closingstring""How the call closes.
script.strictnessflexible, balanced, strictbalancedHow closely the agent follows the steps.
script.ask_first_question_in_greetingboolean—Ask the first question in the greeting.
knowledge.detailsarray of {key, label, value}[]Business facts, such as hours or address.
knowledge.itemsarray of {kind, q, text}[]kind is fact, qa, rule or objection.
knowledge.notesstring""Extra notes.
agent_modeannouncement, awareness, conversation, ivr_survey, surveyconversationThe kind of call.
job_rolestring""Up to 200 characters.
success_criteriastring""What a successful call looks like. Up to 4,000 characters.
required_fieldsarray 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

FieldTypeDefaultNotes
ttsstringsarvamText-to-speech provider. Use a provider value from listVoices.
voicestring""A voiceId from listVoices for the tts provider.
agent_genderfemale, male, anyany
tonestringnatural
caller_namestring""The name the agent uses. Up to 120 characters.
tts_speednumber1.0From 0.5 to 1.5.
tts_volumenumber1.0From 0.2 to 1.0.
background_sound.enabledbooleanfalsePlay a background sound.
background_sound.presetstringoffSound name, for example office.
background_sound.volumenumber0.5From 0.02 to 1.0.

Language and speech-to-text

FieldTypeDefaultNotes
languagestringen-INMain language. Must be an active language from listVoices languages.
extra_languagestring""A second language.
auto_adapt_languagebooleanfalseSwitch language to match the caller.
sttdeepgram, openai, sarvam, sonioxdeepgramSpeech-to-text provider.
noise_reductionoff, standard, strongstandard

Language model

FieldTypeDefaultNotes
llm_modelstringgpt-4o-miniThe model that writes replies.
temperaturenumber0.55From 0 to 2.
max_tokensinteger250From 1 to 32000. Longest reply per turn.
reasoning_effortnone, minimal, low, medium, high, xhigh, maxminimalFor reasoning models.
voice_enginepipeline, gemini_live, openai_realtime, elevenlabs_agentspipelinepipeline chains speech-to-text, the model and text-to-speech.
realtime_model, realtime_voicestring—Used with a realtime voice_engine.

Turn-taking

FieldTypeDefaultNotes
interrupt_modetime, wordstimeHow the caller interrupts the agent.
interrupt_min_speech_msinteger220From 100 to 2000. Speech needed to interrupt, in time mode.
interrupt_word_countinteger2From 1 to 3. Words needed to interrupt, in words mode.
interruption_sensitivitylow, medium, highmedium
conversation_enginev1, v2v1

Compliance

FieldTypeDefaultNotes
ai_disclosurebooleantrueThe agent says it is an AI.
recording_noticebooleantrueThe agent says the call is recorded.
call_recordingbooleantrueRecord the call.

Limits and calling

FieldTypeDefaultNotes
call_time_limit_secondsinteger600From 10 to 3600. The call ends at this limit.
calling_mode"", instant, bulk""

Inline tools

FieldTypeDefaultNotes
toolsarray[]Inline tools. Up to 32. See Tools.
tools[].kindstring—end_call, transfer_call, api_request, function, mcp, lookup_open_tickets, create_ticket, add_ticket_note, schedule_callback or send_whatsapp.
tools[].namestring—Up to 128 characters.
tools[].descriptionstring—Up to 2,000 characters. Tells the model when to use the tool.
tools[].enabledbooleantrue
tools[].configobject{}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_url must be a public http(s) address. An absolute path is used as the base only when base_url is 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.
  • method is GET, POST, PUT, PATCH or DELETE. The default is POST.
  • Requests go only to public addresses and do not follow redirects.

Post-call

FieldTypeNotes
post_call_webhookobject {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's provider;
  • config.voice = its voiceId;
  • config.language = a language id that appears in the voice's languageCodes.

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 whole script object. Any script field you leave out is cleared.
  • name applies at once. It changes the display name immediately and also sets caller_name in 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_invalid for a bad value, voice or language;
  • agent_state_blocked when the script and knowledge are over the size limit, when the text uses an unknown @ token, or when a webhook or api_request tool 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 assignedPhoneNumbers and 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.

FieldTypeRequiredNotes
phoneNumberIdstringyesThe ID of one of your phone numbers, from listPhoneNumbers.
destinationstringyesThe phone to call. E.164 (+919812345678) or a local number.
dynamicValuesobjectnoValues 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:

CodeWhen
resource_not_foundphoneNumberId is not one of your numbers (param is phoneNumberId).
agent_test_call_failedThe call could not be placed, for example the free test-call cap is reached or the carrier refused it.
payment_requiredYour 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.

FieldTypeDefaultNotes
urlstring—A public address, up to 2,000 characters. Send "" to remove the webhook.
secretstring—Signing secret, up to 500 characters. Leave it out to keep the current secret.
triggerevery, completed, voicemaileveryWhich 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 with PATCH, 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_agent until 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"
  }
}
CodeStatusWhen
parameter_invalid422A 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_large413config is larger than 512 KB.
agent_state_blocked422Publish or go-live is refused, content is over the limit, or a URL is not public.
agent_not_found404The agent ID does not exist in this workspace.
agent_test_call_failed400The test call could not be placed.
tool_not_found404The tool ID does not exist.
payment_required402Your plan's agent limit is reached, or the feature is not in your plan.
permission_denied403The key cannot write agents.

On this page