Docs
Open dashboard
Developers

API quickstart

Place your first call over the API in three requests, then read the result back.

Before you start

  • A workspace whose plan includes API & MCP access (Growth and above). Otherwise every request is refused with 403 and the message that API access is not included in the plan.
  • Credits on the workspace: a call request is refused with 403 and 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.

  1. Create a key

    Create a workspace API key under Configuration → General → API Keys. See API keys.

  2. 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.

  3. 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. to must be E.164 (a leading + and country code); anything else is a 400 invalid_request. variables are passed to the agent exactly as sent, so use the names the prompt expects. Reference: Create outbound call.

  4. 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 with start_date set to today, and open it with Get call using the record's id (the call object's stable UUID; call_id holds the provider reference you kept). Until the analysis has run, the disposition and summary fields are empty and call_status shows 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.

StatusCodeMeaning
400invalid_requestA field is missing or malformed, for example a phone number that is not E.164.
401unauthorizedThe key is missing, wrong or revoked.
403forbiddenThe 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.
404not_foundNo such agent or call in this workspace, or the call is past the workspace's retention window.
429rate_limitedToo 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.

Create a Grok Voice agent — POST /v1/agents
{
  "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?"
  }
}
Switch to GPT-Live — PATCH /v1/agents/{id}
{
  "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.

Go to workspace