Docs
Open dashboard

Create agent

POST/agents

Create a new agent in this workspace. Provider credentials must be configured before the agent can place or receive calls. Returns 409 if an agent with the same name already exists. VAPI provisioning failures return 502 provider_error with error.agent_id and error.saved = true when the local agent was retained. Correct the voice or integration and PATCH that ID instead of issuing another POST. For Duplex, keep provider = inspra and set config.voice_mode = duplex with config.realtime_settings containing provider, model and voice. Grok Voice uses xai / xai-realtime/grok-voice-latest / ara; GPT-Live uses openai / gpt-live / marin (or another voice from that model's built-in set). Realtime credentials are managed by the Inspra runtime.

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

Body application/json

  • namestring1–40 charsrequired
    Human-readable agent name. Enforced 1-40 chars.
  • descriptionstringoptional
    Optional free-form notes. Not shown to callers.
  • providerstringrequired
    Voice agent runtime. inspra is the native Inspra runtime.
    inspra
  • voice_providerstringoptional
    Text-to-speech engine. Omit it to use the native Inspra voices from GET /voices. Use inspra-s for optional Indian-language synthesis with a compatible speaker and model.
  • model_providerstringoptional
    LLM provider for the conversation.
    openaianthropicgooglegroqxai
  • transcriber_providerstringoptional
    Speech-to-text engine.
    inspra-dinspra-a
  • agent_directionstringoptional
    Primary calling direction. inbound agents receive calls; outbound agents place them. Defaults to inbound if omitted.
    Default "inbound"
    inboundoutbound
  • allow_outboundbooleanoptional
    For inbound agents, when true the agent may also be selected by outbound endpoints (place call, campaigns).
  • assigned_phone_number_idstringnullableoptional
    UUID of a phone number from Telephony → Phone numbers. Inbound: the dialable number. Outbound: the displayed caller ID.
  • knowledge_document_idsstring[]optional
    IDs of knowledge documents to link to the agent (see the Knowledge Base endpoints). Defaults to none.
  • 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.

Response 201 Created

Agent created.

  • 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

  • 400Bad Request
    Validation failed / malformed request.
  • 401Unauthorized
    Missing, malformed, or invalid API key.
  • 403Forbidden
    Workspace unavailable, suspended, or paywalled.
  • 409Conflict
    Request conflicts with current resource state.
  • 429Too Many Requests
    Workspace request limit exceeded; shared across all its API keys.