Update agent
PATCH/agents/{id}
Partial update — send only the fields you want to change. To clear assigned_phone_number_id send null.
To enable Duplex or change its model/voice, send config.voice_mode = duplex and a complete config.realtime_settings object. A prompt-only config update on an agent with a saved voice mode preserves its mode and speech settings. To restore the saved Standard configuration, send config.voice_mode = cascade. Read the agent back to verify the saved mode, model and voice before calling.
Requires
Authorization: Bearer <api_key>. Create a key under Configuration → General → API Keys.Path parameters
- idstringrequiredUUID of the resource.
Body application/json
- namestring1–40 charsoptionalHuman-readable agent name. 1-40 chars when present.
- descriptionstringoptionalOptional free-form notes.
- providerstringoptionalVoice agent runtime. Changing this after creation may invalidate provider-specific config keys.
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.
openaianthropicgooglegroqxai - transcriber_providerstringoptionalSpeech-to-text engine.
inspra-dinspra-a - agent_directionstringoptionalPrimary calling direction.
inboundoutbound - allow_outboundbooleanoptionalFor inbound agents, when true outbound endpoints may select this agent.
- assigned_phone_number_idstringnullableoptionalUUID of a workspace phone number from Telephony → Phone numbers; null to unassign.
- knowledge_document_idsstring[]optionalReplaces the agent's linked knowledge documents with this list. An empty array removes all links; omit the field to leave them attached.
- 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 200 OK
Updated agent.
- 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.
- 404Not FoundResource not found in this workspace.
- 429Too Many RequestsWorkspace request limit exceeded; shared across all its API keys.