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.

Requires Authorization: Bearer <api_key>. Create a key in the Inspra dashboard under Workspace Settings → 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. vapi (Vapi.ai), retell (Retell AI), or inspra (native Inspra runtime). Once chosen, the workspace must have credentials for this provider configured.
vapiretellinspra
voice_providerstringoptional
Text-to-speech engine. Must be available in this workspace.
elevenlabsdeepgramazureopenaicartesiagoogle_tts
model_providerstringoptional
LLM provider for the conversation.
openaianthropicgooglegroqxai
transcriber_providerstringoptional
Speech-to-text engine.
deepgramassemblyaiopenai
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 Workspace Settings → Phone Numbers. Inbound: the dialable number. Outbound: the displayed caller ID.
configobjectoptional
Provider-agnostic agent configuration. Open object — only the commonly used fields are documented; additional provider-specific keys (e.g. VAPI custom_voice, transcriber_settings, knowledge_base) are accepted and round-tripped as-is. Mirrors the config block of createWorkspaceAgentSchema in types/api.types.ts.
8 fields
- 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). Only used when agent_speaks_first is true for VAPI; other providers may ignore this.
- agent_speaks_firstbooleanoptional
  VAPI-only. When true, the agent opens the call by saying first_message. When false, the agent waits for the caller to speak first. When omitted, the VAPI integration treats it as true (runtime convention; the field is not stored with a default, so GET responses show it as absent unless you set it explicitly).
- voice_idstringoptional
  Provider-specific voice identifier. Look up IDs in the voice provider's dashboard (e.g. ElevenLabs voice library, Cartesia voices, Azure neural voices). Must match the agent's voice_provider.
- voice_settingsobjectoptional
  Voice synthesis tuning. All values are provider-specific; the listed ranges are validated by the API but each voice provider (ElevenLabs, Azure, Cartesia, etc.) applies its own mapping. Omitted fields fall back to the provider's defaults.
  5 fields
  - stabilitynumber0–1optional
    ElevenLabs-style stability. 0 = more variation/expressive, 1 = monotone/consistent. Defaults to the provider's preset when omitted.
  - similarity_boostnumber0–1optional
    ElevenLabs-style 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. ElevenLabs treats this as roughly semitone-scale; other providers map it differently.
  - speaking_ratenumber0.25–4optional
    Alternative pacing knob accepted by the API but not forwarded by the current VAPI or Retell integrations (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 Inspra UI 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. vapi (Vapi.ai), retell (Retell AI), or inspra (native Inspra runtime). Determines which integration credentials and config keys apply.
vapiretellinspra
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. One of elevenlabs, deepgram, azure, openai, cartesia, google_tts. Must be one the workspace has credentials for.
model_providerstringnullableoptional
LLM provider for the conversation. One of openai, anthropic, google, groq, xai.
transcriber_providerstringnullableoptional
Speech-to-text engine. One of deepgram, assemblyai, openai.
assigned_phone_number_idstringnullableoptional
UUID of a phone number from Workspace Settings → 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.
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. VAPI custom_voice, transcriber_settings, knowledge_base) are accepted and round-tripped as-is. Mirrors the config block of createWorkspaceAgentSchema in types/api.types.ts.
8 fields
- 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). Only used when agent_speaks_first is true for VAPI; other providers may ignore this.
- agent_speaks_firstbooleanoptional
  VAPI-only. When true, the agent opens the call by saying first_message. When false, the agent waits for the caller to speak first. When omitted, the VAPI integration treats it as true (runtime convention; the field is not stored with a default, so GET responses show it as absent unless you set it explicitly).
- voice_idstringoptional
  Provider-specific voice identifier. Look up IDs in the voice provider's dashboard (e.g. ElevenLabs voice library, Cartesia voices, Azure neural voices). Must match the agent's voice_provider.
- voice_settingsobjectoptional
  Voice synthesis tuning. All values are provider-specific; the listed ranges are validated by the API but each voice provider (ElevenLabs, Azure, Cartesia, etc.) applies its own mapping. Omitted fields fall back to the provider's defaults.
  5 fields
  - stabilitynumber0–1optional
    ElevenLabs-style stability. 0 = more variation/expressive, 1 = monotone/consistent. Defaults to the provider's preset when omitted.
  - similarity_boostnumber0–1optional
    ElevenLabs-style 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. ElevenLabs treats this as roughly semitone-scale; other providers map it differently.
  - speaking_ratenumber0.25–4optional
    Alternative pacing knob accepted by the API but not forwarded by the current VAPI or Retell integrations (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 Inspra UI 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.