List Voices

Returns all cached voices from the ultravox_voices database table. Voices are global (shared across all agencies) and are read from the local cache -- no external API key is needed for this endpoint.

Endpoint

Property	Value
Function Name	voices-list
HTTP Method	GET
Authentication	Supabase JWT (Bearer token)
Required Role	Any authenticated user

Request

Headers

Authorization: Bearer <supabase_jwt_token>

Query Parameters

Field	Type	Required	Description
language	string	No	Filter by primary language code (e.g., en, es)

Response

Success (200)

{
  "voices": [
    {
      "id": "ultravox-voice-id",
      "name": "Kore",
      "description": "A warm, professional voice",
      "language_label": "English (US)",
      "primary_language": "en",
      "ownership": "public",
      "billing_style": "VOICE_BILLING_STYLE_INCLUDED",
      "provider": "cartesia",
      "preview_url": "https://...",
      "definition": { },
      "last_synced_at": "2025-01-15T12:00:00Z"
    }
  ],
  "total": 42,
  "last_synced_at": "2025-01-15T12:00:00Z",
  "sync_recommended": false
}

The sync_recommended field is true when the voices list is empty or the last sync was more than 24 hours ago.

Error Responses

Status	Condition
401	Missing or invalid authorization header
405	HTTP method is not GET
500	Database query failed

Behavior

• Authenticates the user via Supabase JWT
• Queries the ultravox_voices table ordered by name
• Applies optional language filter against the language column if provided
• Checks the last_synced_at timestamp and sets sync_recommended: true if the data is empty or older than 24 hours
• Returns all matching voice records

Database Tables Read

Table	Operation	Purpose
ultravox_voices	Read	Retrieve cached voice data

Related Functions

• Sync Voices -- Sync voices from Ultravox into the local cache