Build, run and observe voice agents over the phone and the web.
The complete HTTP and WebSocket reference for the VoiceAI Platform. Configure an agent, connect a caller, and read back the transcript, metrics and recording — every operation below is generated directly from the running service.
Before you start
Authentication, limits and failure modes
Everything you send is scoped to your tenant, resolved from the credential you present. There is no tenant parameter on normal endpoints.
Bearer token
For interactive clients. POST /api/v1/auth/login returns an access and a
refresh token. Send the access token on every request; exchange the refresh token at
/api/v1/auth/refresh rather than logging in again.
Authorization: Bearer <access_token>
API key
For servers. Create at POST /api/v1/api-keys. The secret is shown
once — at creation and on rotation. A key carries the exact permissions of
the user who made it.
X-API-Key: vk_9tK…
Access levels
- Public — 20 endpoints, no credential
- User — 194, any tenant member
- Tenant admin — 7, role
owner/admin - Platform admin — 14, cross-tenant
- Internal — 8, agent worker only
Rate limits
Sliding window per credential. Authenticated traffic starts at 120 req/min,
5,000/hour, 50,000/day. Every response carries
X-RateLimit-Remaining; a 429 carries Retry-After.
Errors
Handled errors return {"detail": "…"}; a 422 returns per-field entries
under detail[].loc. Rate limits and unhandled faults return
{"error": {"code", "message"}}. Retry 429/500/503 with backoff — never 403.
Paging
List endpoints take page (1-based) and page_size, and return
{items, total, page, page_size}. Filters vary by resource —
commonly search, status, agent_id,
start_date, end_date.
Real time
Two ways to hold a conversation
Audio never travels over the REST API. You either open the voice WebSocket directly, or mint a LiveKit token and let the WebRTC SFU carry the media.
wss://…/ws/voice
The browser pipeline. Send session.start, then stream raw PCM as binary
frames. You receive transcript.partial / transcript.final,
response.text.delta, and the agent's audio as binary frames.
Stop playback on response.interrupted — buffered audio past that
point was never heard, and the transcript records only text_spoken.
LiveKit WebRTC
POST /api/v1/livekit/token returns a token, room name, LiveKit URL and
the call_id you'll query afterwards. Per-session overrides
(system_prompt, voice_id, …) apply without mutating the
saved agent.
wss://…/api/v1/sessions/live
Read-only monitoring feed for a tenant's active sessions. Pass the JWT as a
token query parameter — an invalid token closes with code
4001.
Webhooks
Set webhook_url on an agent. Deliveries are signed with
X-VoiceAI-Signature: sha256=… over the raw body, retried 3× at 1s/5s/30s,
then dead-lettered. Deduplicate on X-VoiceAI-Delivery-ID.
No endpoint matches those filters.