List agents

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.
  vapiretellinspra
• 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
  16 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. 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.
• 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.