API reference

Voice

Browse the voices available to your workspace and map phone numbers to bots so callers reach the right agent. Read endpoints need voice:read; create/update/delete need voice:write.

Endpoints

Method & path	Ability	Notes
`GET /api/v1/voice/catalog`	`voice:read`	Available voices
`GET /api/v1/voice/usage?session_token=`	`voice:read`	Widget voice-session usage
`GET /api/v1/voice/numbers`	`voice:read`	List (metadata filters; no pagination)
`POST /api/v1/voice/numbers`	`voice:write`	Create → `{ id }`
`GET /api/v1/voice/numbers/{id}`	`voice:read`
`PUT /api/v1/voice/numbers/{id}`	`voice:write`	Update; can set `is_outbound_primary` (422 if not outbound-capable)
`DELETE /api/v1/voice/numbers/{id}`	`voice:write`
`PATCH /api/v1/voice/numbers/{id}/metadata`	`voice:write`	Raw metadata object

Voice catalog

GET /api/v1/voice/catalog returns the voices you can assign (filtered to providers that have a key configured): { "voices": [{ "id": "…", "name": "…", "language": "…", "gender": "…" }] }.

Voice numbers

A voice number maps an inbound phone number to a bot. Object fields: id, phone_number, bot_id, bot_name, tenant_id, greeting, tts_voice, optional metadata, created_at, updated_at.

Create with POST /api/v1/voice/numbers:

{
  "phone_number": "+15551234567",
  "bot_id": "b1f2c3d4-…",
  "greeting": "Thanks for calling!",
  "tts_voice": "voice_id"
}

phone_number and bot_id are required; greeting, tts_voice, and metadata are optional. On PUT, metadata follows a keep-on-omit rule (omit to keep, send {} to clear). You can also set is_outbound_primary on PUT to make this number the caller ID for outbound calls - the number must be outbound-capable, or the request returns 422.

Voice session usage

GET /api/v1/voice/usage?session_token= reports usage for an in-browser voice-widget session, identified by its session_token. The embeddable voice widget uses it to meter a live session; server-to-server integrations don't normally call it.