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/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 → message only
`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).