Docs
Open dashboard

List agents

GET/agents

Returns agents in this workspace, newest first. Use provider, is_active, direction, and search to filter. Responses omit config — fetch a single agent for the full config.

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

Query parameters

  • pageinteger≥ 1optional
    1-based page index. Defaults to 1.
    Default 1
  • page_sizeinteger1–100optional
    Items per page. Defaults to 20. Hard-capped at 100 by the server.
    Default 20
  • providerstringoptional
    Filter to a single agent runtime.
    inspra
  • is_activebooleanoptional
    When true, return only active agents; when false, only inactive. Omit for both.
  • directionstringoptional
    Filter by the agent's agent_direction.
    inboundoutbound
  • searchstringoptional
    Case-insensitive substring match against the agent's name and description.

Response 200 OK

Paginated agent list.

  • dataobject[]required
    19 fields
    • 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.
  • paginationobjectrequired
    Echoed pagination block on every list response. page and page_size match the request (or the defaults if omitted); total is the count of matching rows across all pages.
    3 fields
    • pageinteger≥ 1required
      1-based page index of this response.
    • page_sizeinteger≥ 1required
      Number of items per page (request cap is 100).
    • totalinteger≥ 0required
      Total matching items across all pages.

Errors

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