Skip to main content

List Agents

Fetches all agents from the Ultravox API and merges them with local agent_mappings data to produce a combined view. Each agent in the response includes both Ultravox call template configuration and Virsyn client/campaign assignment information. Also returns lists of available clients and campaigns for use in assignment dropdowns.

Endpoint​

PropertyValue
Function Nameagents-list
HTTP MethodGET
AuthenticationSupabase JWT (Bearer token)
Required RoleAny agency user (no specific role required beyond agency membership)

Request​

Headers​

Authorization: Bearer <supabase_jwt_token>
Content-Type: application/json

Query Parameters​

FieldTypeRequiredDescription
cursorstringNoPagination cursor returned from a previous response's pagination.next or pagination.previous field.
limitnumberNoNumber of agents to return per page. Defaults to 50. Maximum is 100.

Response​

Success (200)​

{
  "agents": [
    {
      "ultravox_agent_id": "uv-agent-abc123",
      "name": "My_Agent",
      "created": "2025-01-15T10:30:00Z",
      "system_prompt": "You are a helpful assistant...",
      "voice": "terrence",
      "language_hint": "en",
      "temperature": 0.4,
      "recording_enabled": true,
      "max_duration": "3600s",
      "first_speaker_settings": {
        "agent": { "text": "Hello, how can I help you?" }
      },
      "selected_tools": [],
      "mapping": {
        "id": "uuid-of-mapping",
        "client_id": "uuid-of-client",
        "client_name": "Acme Corp",
        "campaign_id": "uuid-of-campaign",
        "campaign_name": "Q1 Outreach",
        "campaign_type": "outbound",
        "default_direction": "outbound",
        "managed_by_virsyn": true,
        "last_synced_at": "2025-01-15T12:00:00Z",
        "sync_error": null
      }
    }
  ],
  "clients": [
    { "id": "uuid-of-client", "name": "Acme Corp" }
  ],
  "campaigns": [
    { "id": "uuid-of-campaign", "name": "Q1 Outreach", "type": "outbound", "client_id": "uuid-of-client" }
  ],
  "pagination": {
    "next": "cursor-string-or-null",
    "previous": "cursor-string-or-null",
    "total": 25
  }
}

The mapping field on each agent is null if no local mapping exists for that Ultravox agent.

Error Responses​

StatusCondition
400Ultravox API key is not configured for the agency
401Missing or invalid authorization header
403User is not associated with an agency
405HTTP method is not GET
500Unexpected server error
502Ultravox API returned an error when fetching agents

Behavior​

  • Authenticates the user via Supabase JWT and verifies they belong to an agency.
  • Retrieves the agency's Ultravox API key by calling the get_agency_credentials RPC function.
  • Parses optional cursor and limit query parameters for pagination. Clamps limit to a maximum of 100.
  • Sends a GET request to https://api.ultravox.ai/api/agents with the pagination parameters.
  • Fetches all agent_mappings records for the agency, including joined clients (id, name) and campaigns (id, name, type) data.
  • Builds a lookup map of mappings keyed by ultravox_agent_id for efficient merging.
  • Merges each Ultravox agent with its corresponding local mapping (if one exists). Extracts call template fields (system prompt, voice, language hint, temperature, recording enabled, max duration, first speaker settings, selected tools) from the Ultravox response.
  • Additionally fetches active clients and active campaigns belonging to the agency (ordered by name) for use in frontend assignment dropdowns.
  • Returns the merged agent list, client/campaign lists, and pagination metadata.

Database Tables​

TableOperationDescription
usersReadFetches user profile to determine agency_id
agent_mappingsReadFetches all local mappings for the agency, with joined clients and campaigns
clientsReadFetches active clients for the agency (for assignment dropdowns)
campaignsReadFetches active campaigns for the agency (for assignment dropdowns)

External APIs​

APIMethodEndpointDescription
UltravoxGET/api/agentsFetches paginated list of agents