Docs
Open dashboard

Get agent

GET/agents/{id}

Returns a single agent including its full config block.

Requires Authorization: Bearer <api_key>. Create a key under Configuration → General → API Keys.

Path parameters

  • idstringrequired
    UUID of the resource.

Response 200 OK

Agent (includes config).

  • idstringoptional
    Stable UUID of the agent within this workspace.
  • workspace_idstringoptional
    UUID of the owning workspace. Always matches the workspace bound to the API key.
  • namestringoptional
    Human-readable agent name. 1-40 chars.
  • descriptionstringnullableoptional
    Free-form notes about the agent. Not shown to callers.
  • providerstringoptional
    Voice agent runtime. inspra is the native Inspra runtime.
    inspra
  • is_activebooleannullableoptional
    When false, the agent is hidden from selection lists and cannot place or receive calls.
  • agent_directionstringnullableoptional
    Primary calling direction. inbound receives calls; outbound places calls (manual + campaign). An inbound agent can still place outbound calls when allow_outbound is true.
    inboundoutbound
  • allow_outboundbooleannullableoptional
    For inbound agents, when true the agent may be selected by outbound endpoints (place call, campaigns).
  • voice_providerstringnullableoptional
    Text-to-speech engine. inspra for the native voices from GET /voices. Optional inspra-s speech uses IDs such as inspra-s/shubh. Runtime speech is handled by the existing backend.
  • model_providerstringnullableoptional
    LLM provider for the conversation. One of openai, anthropic, google, groq, xai.
  • transcriber_providerstringnullableoptional
    Speech-to-text engine. One of inspra-d, inspra-a.
  • assigned_phone_number_idstringnullableoptional
    UUID of a phone number from Telephony → Phone numbers. For inbound agents this is the number callers dial; for outbound agents (or allow_outbound=true) it is the displayed caller ID.
  • sync_statusstringnullableoptional
    Last known sync state with the upstream provider (e.g. synced, pending, not_synced, error). Read-only; populated by the platform.
  • last_sync_errorstringnullableoptional
    Provider failure details. Included in single-agent and mutation responses; omitted from lists.
  • kb_sync_statusstringoptional
    Knowledge sync state. Included in single-agent and mutation responses.
  • kb_sync_errorstringnullableoptional
    Knowledge sync failure details. Included in single-agent and mutation responses.
  • created_atstringnullableoptional
    ISO 8601 UTC timestamp when the agent was created.
  • updated_atstringnullableoptional
    ISO 8601 UTC timestamp of the last update.
  • configobjectoptional
    Provider-agnostic agent configuration. Open object — only the commonly used fields are documented; additional provider-specific keys (e.g. transcriber_settings, knowledge_base) are accepted and round-tripped as-is. Mirrors the config block of createWorkspaceAgentSchema in types/api.types.ts.
    14 fields
    • voice_modestringoptional
      Inspra voice pipeline. cascade is labelled Standard in the UI (separate STT, LLM and TTS). Legacy agents with neither voice_mode nor realtime_settings use Standard. Set voice_mode explicitly when supplying realtime_settings or changing modes. Duplex uses Grok Voice or GPT-Live and requires a complete realtime_settings object. Existing Standard settings are preserved for switching back. Other agent providers do not support duplex.
      cascadeduplex
    • realtime_settingsobjectoptional
      Inspra Duplex configuration. These settings are independent of voice_id, model_settings and transcriber_settings, which apply to Standard mode. The top-level voice_provider and model_provider do not select Duplex engines. All three fields (provider, model and voice) are required; voices must belong to the selected model. Provider credentials are managed by the Inspra runtime; do not include API keys here. GET /voices lists Standard voices, not these built-in realtime voices.
      2 variants
      Option 1
      • providerstringoptional
        Realtime provider for Grok Voice.
        xai
      • modelstringoptional
        Legacy bare Grok IDs normalize to xai-realtime/grok-voice-latest.
        xai-realtime/grok-voice-latestgrok-voice-latestgrok-voice-3.0
      • voicestringoptional
        Built-in Grok Voice ID. Rigel is the Australian voice. UI default is ara; API requests must include voice.
        Default "ara"
        araeveleorexsalatlaslunairisorionhelixcarinazaganaltairzenithperseusheliosluxkeplerrigelcosmocelesteursasiriuslumencastornaksh
      Option 2
      • providerstringoptional
        Realtime provider for GPT-Live.
        openai
      • modelstringoptional
        GPT-Live realtime speech model.
        gpt-live
      • voicestringoptional
        Built-in GPT-Live voice ID. UI default is marin; API requests must include voice.
        Default "marin"
        marincedarbeaconcinderstonevesperquartzripple
    • tts_modelstringoptional
      Speech model. Inspra S synthesis currently supports bulbul:v3.
    • speech_outputobjectoptional
      Paid-preview preferences for optional Inspra S voices. Not sent to the runtime worker.
      1 field
      • language_codestringoptional
        Supported preview language, such as en-IN or hi-IN.
    • transcriber_settingsobjectoptional
      Native transcription settings sent through the existing deployment API.
      3 fields
      • providerstringoptional
        Transcription engine, including inspra-s for optional Indian-language recognition.
      • modelstringoptional
        Inspra S currently supports saaras:v3.
      • languagestringoptional
        A supported recognition language. Recognition and synthesis have separate language support.
    • system_promptstringoptional
      The agent's role and instructions, sent to the LLM as a system message at the start of every call. Plain text; supports template variables that get filled from the variables map on place-call.
    • first_messagestringoptional
      What the agent says first when it answers (inbound) or the call connects (outbound).
    • agent_speaks_firstbooleanoptional
      When true, the agent opens the call by saying first_message. When false, the agent waits for the caller to speak first. Only honoured by runtimes that support it. When omitted it is treated as true (runtime convention; the field is not stored with a default, so GET responses show it as absent unless you set it explicitly).
    • integration_selectionsobjectoptional
      Explicit VAPI integration selection; omitted means Auto. A workspace API key's name does not select the provider account. Unavailable explicit selections fail instead of falling back to another account.
    • voice_idstringoptional
      Standard-mode voice identifier. List the available voices with GET /voices and use the returned id (e.g. inspra/46e236a3...). Duplex uses realtime_settings.voice instead; this saved Standard voice is inactive while Duplex is selected.
    • voice_settingsobjectoptional
      Voice synthesis tuning. All values are provider-specific; the listed ranges are validated by the API but each voice provider applies its own mapping. Omitted fields fall back to the provider's defaults.
      5 fields
      • stabilitynumber0–1optional
        Voice stability. 0 = more variation/expressive, 1 = monotone/consistent. Defaults to the provider's preset when omitted.
      • similarity_boostnumber0–1optional
        Adherence to the original voice clone. 0 = looser, 1 = stricter. Higher values can amplify clone artifacts.
      • speednumber0.5–2optional
        Playback-rate multiplier. 1 = normal. 0.5 = half speed, 2 = double speed. Distinct from speaking_rate (which targets the synthesis engine's own pacing).
      • pitchnumber-20–20optional
        Pitch offset in provider-specific units. 0 = unchanged. Negative = lower, positive = higher. The scale varies by voice provider.
      • speaking_ratenumber0.25–4optional
        Alternative pacing knob accepted by the API but not currently forwarded to the voice runtime (only speed is). Provided for forward-compatibility with providers that distinguish synthesis pacing from playback rate. 1 = normal.
    • max_duration_secondsinteger60–3600optional
      Maximum total call length in seconds. Hard cap is 1 hour (3600s). The agent ends the call automatically when this elapses.
    • end_call_phrasesstring[]optional
      Phrases the caller or agent can say to end the call gracefully (e.g. "goodbye", "thanks bye"). Provider-specific matching rules.
    • toolsobject[]optional
      Function-calling tools the agent can invoke mid-call. Each item is a provider-specific tool definition (free-form to allow provider evolution). See the dashboard agent editor for the canonical shapes per provider.

Errors

  • 401Unauthorized
    Missing, malformed, or invalid API key.
  • 403Forbidden
    Workspace unavailable, suspended, or paywalled.
  • 404Not Found
    Resource not found in this workspace.
  • 429Too Many Requests
    Workspace request limit exceeded; shared across all its API keys.