Before you start
- A workspace whose plan includes API & MCP access (Growth and above). Otherwise every request is refused with
403and the message that API access is not included in the plan. - Credits on the workspace: a call request is refused with
403and Insufficient credits to fund the next call when the balance cannot fund the next billable unit. Reads still work. - An outbound agent (or an inbound agent with outbound campaigns allowed) that is active and, for Vapi or Retell, synced.
The examples use two placeholders: $API_BASE_URL is the API host, https://api.inspra.ai (or https://<your domain>), and $API_KEY is your workspace API key. See Base URL.
Create a key
Create a workspace API key under Configuration → General → API Keys. See API keys.
Find the agent
List agents and copy the ID of an outbound agent.
cURL curl "$API_BASE_URL/v1/agents" \ -H "Authorization: Bearer $API_KEY"Response (abridged) { "data": [ { "id": "7e3b3c54-2c1f-4d8b-9a3e-2f9b0a7d1c01", "name": "Harbourside reception", "provider": "inspra", "is_active": true, "agent_direction": "outbound", "sync_status": "synced" } ], "pagination": { "page": 1, "page_size": 20, "total": 1 } }Reference: List agents.
Place the call
cURL curl -X POST "$API_BASE_URL/v1/calls" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "7e3b3c54-2c1f-4d8b-9a3e-2f9b0a7d1c01", "to": "+61412345678", "variables": { "first_name": "Priya" } }'Response: 201 Created { "success": true, "provider": "inspra", "callId": "a93f3f85-74e0-4c55-9d3e-1c2b7d0e8f41" }The call is queued, not finished: the response arrives as soon as the provider accepts it.
tomust be E.164 (a leading+and country code); anything else is a400 invalid_request.variablesare passed to the agent exactly as sent, so use the names the prompt expects. Reference: Create outbound call.Read the result
Keep the
callId; it is the provider's reference for the call. Once the call appears in the workspace's call history, find its record with List calls, searching by the number you dialled withstart_dateset to today, and open it with Get call using the record'sid(the call object's stable UUID;call_idholds the provider reference you kept). Until the analysis has run, the disposition and summary fields are empty andcall_statusshows the call in progress, so poll every 30 seconds or so, or let the call-data webhook push the finished record to you.cURL curl "$API_BASE_URL/v1/calls?search=%2B61412345678&start_date=2026-10-06" \ -H "Authorization: Bearer $API_KEY" curl "$API_BASE_URL/v1/calls/a93f3f85-74e0-4c55-9d3e-1c2b7d0e8f41" \ -H "Authorization: Bearer $API_KEY"Response (abridged) { "data": { "id": "a93f3f85-74e0-4c55-9d3e-1c2b7d0e8f41", "call_status": "completed", "agent_call_type": "outbound", "to": "+61412345678", "duration": 214, "disposition": ["interested"], "disposition_status": "POSITIVE_CONNECTED", "summary": "Priya wants to keep her plan and asked for a callback on Thursday.", "transcript": [ { "role": "agent", "text": "Hi Priya, is now a good time?" }, { "role": "user", "text": "Sure…" } ], "variables": { "first_name": "Priya", "callback_day": "Thursday" } } }
Errors
Every non-2xx response carries the same envelope: { "error": { "code": "...", "message": "..." } }. Branch on the code, not the message.
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | A field is missing or malformed, for example a phone number that is not E.164. |
| 401 | unauthorized | The key is missing, wrong or revoked. |
| 403 | forbidden | The plan does not include API access, the workspace has no credits or has reached its monthly conversation limit, or the workspace is not active. The message says which. |
| 404 | not_found | No such agent or call in this workspace, or the call is past the workspace's retention window. |
| 429 | rate_limited | Too many requests for this workspace. Wait the number of seconds in the Retry-After header. See limits. |
Base URL
The API base URL is https://api.inspra.ai/v1. On your own domain, use https://<your domain>/v1.
In the examples, $API_BASE_URL stands for https://api.inspra.ai (or https://<your domain>), so a request goes to $API_BASE_URL/v1/agents. $API_KEY is your workspace API key.
Duplex models
Use Create agent, Update agent or the MCP create_agent and update_agent tools. Keep the agent provider as inspra, and send config.voice_mode: "duplex" with a complete config.realtime_settings object.
{
"name": "Support",
"provider": "inspra",
"config": {
"voice_mode": "duplex",
"realtime_settings": {
"provider": "xai",
"model": "xai-realtime/grok-voice-latest",
"voice": "ara"
},
"system_prompt": "Help callers using the approved business information.",
"first_message": "Hello, how can I help?"
}
}{
"config": {
"voice_mode": "duplex",
"realtime_settings": {
"provider": "openai",
"model": "gpt-live",
"voice": "marin"
}
}
}Voice IDs are lowercase. Use a voice belonging to the selected model: for example, rigel with Grok Voice or vesper with GPT-Live. New Grok requests should use xai-realtime/grok-voice-latest; legacy grok-voice-latest and grok-voice-3.0 values normalize to that ID.
In Duplex mode, realtime_settings selects the active model and voice. The Standard voice_id, voice_provider, model_provider, model_settings and transcriber_settings do not select the Duplex speech engines. The Inspra runtime manages realtime provider credentials; do not put API keys in realtime_settings. The voice catalogue API lists Standard voices; choose Duplex voices from the model's built-in set.
For a mode change, send voice_mode explicitly. Omitting both voice-mode fields keeps legacy Inspra agents on Standard. A prompt-only update to an agent with a saved voice mode preserves its mode and speech configuration. To return to Standard, send { "config": { "voice_mode": "cascade" } }, then verify the saved configuration with Get agent.
See Manage agents: Duplex model and voice settings for compatible voices, previews and mode switching.