Create agent
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.
Authorization: Bearer <api_key>. Create a key under Configuration → General → API Keys.Body application/json
- namestring1–40 charsrequiredHuman-readable agent name. Enforced 1-40 chars.
- descriptionstringoptionalOptional free-form notes. Not shown to callers.
- providerstringrequiredVoice agent runtime.
insprais the native Inspra runtime.inspra - voice_providerstringoptionalText-to-speech engine. Omit it to use the native Inspra voices from
GET /voices. Useinspra-sfor optional Indian-language synthesis with a compatible speaker and model. - model_providerstringoptionalLLM provider for the conversation.
openaianthropicgooglegroqxai - transcriber_providerstringoptionalSpeech-to-text engine.
inspra-dinspra-a - agent_directionstringoptionalPrimary calling direction.
inboundagents receive calls;outboundagents place them. Defaults toinboundif omitted.Default"inbound"inboundoutbound - allow_outboundbooleanoptionalFor inbound agents, when true the agent may also be selected by outbound endpoints (place call, campaigns).
- assigned_phone_number_idstringnullableoptionalUUID of a phone number from Telephony → Phone numbers. Inbound: the dialable number. Outbound: the displayed caller ID.
- knowledge_document_idsstring[]optionalIDs of knowledge documents to link to the agent (see the Knowledge Base endpoints). Defaults to none.
- configobjectoptionalProvider-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
configblock of createWorkspaceAgentSchema intypes/api.types.ts.14 fields
- voice_modestringoptionalInspra 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_settingsobjectoptionalInspra 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- providerstringoptionalRealtime provider for Grok Voice.
xai - modelstringoptionalLegacy bare Grok IDs normalize to xai-realtime/grok-voice-latest.
xai-realtime/grok-voice-latestgrok-voice-latestgrok-voice-3.0 - voicestringoptionalBuilt-in Grok Voice ID. Rigel is the Australian voice. UI default is ara; API requests must include voice.Default
"ara"araeveleorexsalatlaslunairisorionhelixcarinazaganaltairzenithperseusheliosluxkeplerrigelcosmocelesteursasiriuslumencastornaksh
Option 2- providerstringoptionalRealtime provider for GPT-Live.
openai - modelstringoptionalGPT-Live realtime speech model.
gpt-live - voicestringoptionalBuilt-in GPT-Live voice ID. UI default is marin; API requests must include voice.Default
"marin"marincedarbeaconcinderstonevesperquartzripple
- tts_modelstringoptionalSpeech model. Inspra S synthesis currently supports bulbul:v3.
- speech_outputobjectoptionalPaid-preview preferences for optional Inspra S voices. Not sent to the runtime worker.
1 field
- language_codestringoptionalSupported preview language, such as en-IN or hi-IN.
- transcriber_settingsobjectoptionalNative transcription settings sent through the existing deployment API.
3 fields
- providerstringoptionalTranscription engine, including inspra-s for optional Indian-language recognition.
- modelstringoptionalInspra S currently supports saaras:v3.
- languagestringoptionalA supported recognition language. Recognition and synthesis have separate language support.
- system_promptstringoptionalThe 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
variablesmap on place-call. - first_messagestringoptionalWhat the agent says first when it answers (inbound) or the call connects (outbound).
- agent_speaks_firstbooleanoptionalWhen 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_selectionsobjectoptionalExplicit 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_idstringoptionalStandard-mode voice identifier. List the available voices with
GET /voicesand use the returnedid(e.g.inspra/46e236a3...). Duplex uses realtime_settings.voice instead; this saved Standard voice is inactive while Duplex is selected. - voice_settingsobjectoptionalVoice 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–1optionalVoice stability. 0 = more variation/expressive, 1 = monotone/consistent. Defaults to the provider's preset when omitted.
- similarity_boostnumber0–1optionalAdherence to the original voice clone. 0 = looser, 1 = stricter. Higher values can amplify clone artifacts.
- speednumber0.5–2optionalPlayback-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–20optionalPitch offset in provider-specific units. 0 = unchanged. Negative = lower, positive = higher. The scale varies by voice provider.
- speaking_ratenumber0.25–4optionalAlternative pacing knob accepted by the API but not currently forwarded to the voice runtime (only
speedis). Provided for forward-compatibility with providers that distinguish synthesis pacing from playback rate. 1 = normal.
- max_duration_secondsinteger60–3600optionalMaximum total call length in seconds. Hard cap is 1 hour (3600s). The agent ends the call automatically when this elapses.
- end_call_phrasesstring[]optionalPhrases the caller or agent can say to end the call gracefully (e.g. "goodbye", "thanks bye"). Provider-specific matching rules.
- toolsobject[]optionalFunction-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.
- idstringoptionalStable UUID of the agent within this workspace.
- workspace_idstringoptionalUUID of the owning workspace. Always matches the workspace bound to the API key.
- namestringoptionalHuman-readable agent name. 1-40 chars.
- descriptionstringnullableoptionalFree-form notes about the agent. Not shown to callers.
- providerstringoptionalVoice agent runtime.
insprais the native Inspra runtime.inspra - is_activebooleannullableoptionalWhen false, the agent is hidden from selection lists and cannot place or receive calls.
- agent_directionstringnullableoptionalPrimary calling direction.
inboundreceives calls;outboundplaces calls (manual + campaign). An inbound agent can still place outbound calls whenallow_outboundis true.inboundoutbound - allow_outboundbooleannullableoptionalFor inbound agents, when true the agent may be selected by outbound endpoints (place call, campaigns).
- voice_providerstringnullableoptionalText-to-speech engine.
insprafor the native voices fromGET /voices. Optionalinspra-sspeech uses IDs such asinspra-s/shubh. Runtime speech is handled by the existing backend. - model_providerstringnullableoptionalLLM provider for the conversation. One of
openai,anthropic,google,groq,xai. - transcriber_providerstringnullableoptionalSpeech-to-text engine. One of
inspra-d,inspra-a. - assigned_phone_number_idstringnullableoptionalUUID 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_statusstringnullableoptionalLast known sync state with the upstream provider (e.g.
synced,pending,not_synced,error). Read-only; populated by the platform. - last_sync_errorstringnullableoptionalProvider failure details. Included in single-agent and mutation responses; omitted from lists.
- kb_sync_statusstringoptionalKnowledge sync state. Included in single-agent and mutation responses.
- kb_sync_errorstringnullableoptionalKnowledge sync failure details. Included in single-agent and mutation responses.
- created_atstringnullableoptionalISO 8601 UTC timestamp when the agent was created.
- updated_atstringnullableoptionalISO 8601 UTC timestamp of the last update.
- configobjectoptionalProvider-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
configblock of createWorkspaceAgentSchema intypes/api.types.ts.14 fields
- voice_modestringoptionalInspra 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_settingsobjectoptionalInspra 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- providerstringoptionalRealtime provider for Grok Voice.
xai - modelstringoptionalLegacy bare Grok IDs normalize to xai-realtime/grok-voice-latest.
xai-realtime/grok-voice-latestgrok-voice-latestgrok-voice-3.0 - voicestringoptionalBuilt-in Grok Voice ID. Rigel is the Australian voice. UI default is ara; API requests must include voice.Default
"ara"araeveleorexsalatlaslunairisorionhelixcarinazaganaltairzenithperseusheliosluxkeplerrigelcosmocelesteursasiriuslumencastornaksh
Option 2- providerstringoptionalRealtime provider for GPT-Live.
openai - modelstringoptionalGPT-Live realtime speech model.
gpt-live - voicestringoptionalBuilt-in GPT-Live voice ID. UI default is marin; API requests must include voice.Default
"marin"marincedarbeaconcinderstonevesperquartzripple
- tts_modelstringoptionalSpeech model. Inspra S synthesis currently supports bulbul:v3.
- speech_outputobjectoptionalPaid-preview preferences for optional Inspra S voices. Not sent to the runtime worker.
1 field
- language_codestringoptionalSupported preview language, such as en-IN or hi-IN.
- transcriber_settingsobjectoptionalNative transcription settings sent through the existing deployment API.
3 fields
- providerstringoptionalTranscription engine, including inspra-s for optional Indian-language recognition.
- modelstringoptionalInspra S currently supports saaras:v3.
- languagestringoptionalA supported recognition language. Recognition and synthesis have separate language support.
- system_promptstringoptionalThe 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
variablesmap on place-call. - first_messagestringoptionalWhat the agent says first when it answers (inbound) or the call connects (outbound).
- agent_speaks_firstbooleanoptionalWhen 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_selectionsobjectoptionalExplicit 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_idstringoptionalStandard-mode voice identifier. List the available voices with
GET /voicesand use the returnedid(e.g.inspra/46e236a3...). Duplex uses realtime_settings.voice instead; this saved Standard voice is inactive while Duplex is selected. - voice_settingsobjectoptionalVoice 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–1optionalVoice stability. 0 = more variation/expressive, 1 = monotone/consistent. Defaults to the provider's preset when omitted.
- similarity_boostnumber0–1optionalAdherence to the original voice clone. 0 = looser, 1 = stricter. Higher values can amplify clone artifacts.
- speednumber0.5–2optionalPlayback-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–20optionalPitch offset in provider-specific units. 0 = unchanged. Negative = lower, positive = higher. The scale varies by voice provider.
- speaking_ratenumber0.25–4optionalAlternative pacing knob accepted by the API but not currently forwarded to the voice runtime (only
speedis). Provided for forward-compatibility with providers that distinguish synthesis pacing from playback rate. 1 = normal.
- max_duration_secondsinteger60–3600optionalMaximum total call length in seconds. Hard cap is 1 hour (3600s). The agent ends the call automatically when this elapses.
- end_call_phrasesstring[]optionalPhrases the caller or agent can say to end the call gracefully (e.g. "goodbye", "thanks bye"). Provider-specific matching rules.
- toolsobject[]optionalFunction-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 RequestValidation failed / malformed request.
- 401UnauthorizedMissing, malformed, or invalid API key.
- 403ForbiddenWorkspace unavailable, suspended, or paywalled.
- 409ConflictRequest conflicts with current resource state.
- 429Too Many RequestsWorkspace request limit exceeded; shared across all its API keys.