VoiceAI Platform API

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.

Operations716
Groups—
WebSockets2
Versionv1

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.