API Reference

Overview

The Vaani Backend API provides endpoints for building and configuring voice agents, triggering and managing calls, and connecting in-browser sessions via WebRTC. Except for the few endpoints listed under Endpoints without an API key, all endpoints require API key authentication via the X-API-Key header.

Authentication

All endpoints require API key authentication. Include your API key in the request header:

X-API-Key: vaani_<your_key>

Keep your API key secure and never expose it in client-side code or public repositories.

Endpoints without an API key

Endpoint	How it is protected
`GET /api/health`	Public health check
`POST /api/webrtc/session/connect`, `POST /api/webrtc/session/disconnect`, `GET /api/webrtc/session/status/{session_token}`, WebSocket `/api/webrtc/session/ws/{session_token}`	The `session_token` returned by `POST /api/webrtc/session/create`
`/api/live-transcripts/*` (`stream`, `ws`, `history`, `status`, `url`)	The signed `?token=` in the `live_captions_url` returned by Create Dispatch, or a valid `X-API-Key`

Base URL

All endpoints are prefixed with /api/. The base URL is:

https://api.vaanivoice.ai

Errors

Every error response uses the same JSON body:

{
  "status_code": 404,
  "error": "Not Found",
  "message": "Call with ID abc123 not found",
  "code": "NOT_FOUND",
  "path": "/api/stream/abc123",
  "timestamp": "2026-11-04T06:31:03.388082Z",
  "request_id": "5f2f74b8-c72d-4efe-85aa-8150edf05ee2"
}

Field	Description
`status_code`	HTTP status code of the response
`error`	Short name of the status (e.g. `Unauthorized`, `Not Found`)
`message`	Human-readable description of what went wrong. Always read this field.
`detail`	Same text as `message`. Present on some errors (for example `401` and `422`), always a string
`code`	Machine-readable error code, when the failing service provides one (e.g. `NOT_FOUND`)
`path`	The request path you called
`timestamp`	When the error occurred (UTC)
`request_id`	Unique ID for the request - quote it when contacting support

Validation errors (422) put the failing location and reason in message, for example query -> page: Input should be a valid integer.

Status	Meaning
`401`	Missing or invalid `X-API-Key`
`403`	The key is valid but does not have access to this resource
`404`	The agent, call or other resource does not exist
`422`	The request body, path or query failed validation
`5xx`	Server or upstream error - safe to retry with backoff

API Version

Current API version: 1.0.0 (as reported by /openapi.json)

Agent Builder

Use these endpoints to programmatically create and configure agents via the API.

Method	Endpoint	Description
`POST`	`/api/create-agent`	Create a new agent
`PATCH`	`/api/agent/{agent_id}/persona`	Update identity, AI providers
`PATCH`	`/api/agent/{agent_id}/training`	Update knowledge base, FAQ, guardrails
`PATCH`	`/api/agent/{agent_id}/experience`	Update conversational feel and call settings
`PATCH`	`/api/agent/{agent_id}/analysis`	Update post-call evaluation and data extraction
`PATCH`	`/api/agent/{agent_id}/deployment`	Update phone number routing

PATCH endpoints leave fields you do not send unchanged. Only the AI provider blocks under senses_capabilities are deep-merged; metadata, faq, guardrails, word_pronunciation_pairs, deployment_config and the extraction data_collection.data_points list are replaced whole by the value you send.

Call Management

Method	Endpoint	Description
`POST`	`/api/trigger-call/`	Trigger an outbound phone call, or start a WebRTC session with `medium: "webrtc"` (returns the LiveKit token)
`GET`	`/api/call-history`	Paginated call history
`GET`	`/api/transcript/{call_id}`	Get call transcript
`GET`	`/api/call_details/{call_id}`	Get call details, summary, and extractions
`GET`	`/api/stream/{call_id}`	Stream audio recording. Supports `HEAD` and HTTP `Range` requests (`206 Partial Content`)

Other Endpoints

Method	Endpoint	Description
`GET`	`/api/health`	Health check (no API key needed)
`GET`	`/api/agents`	List agents. Aliases: `/api/agents/`, `/api/list-agents`
`GET`	`/api/agents/{agent_id}`	Full configuration of one agent. Alias: `/api/agent/{agent_id}`
`DELETE`	`/api/agents/{agent_id}`	Delete agent. Alias: `/api/delete-agent/{agent_id}`
`POST`	`/api/webrtc/session/create`	Create an embeddable WebRTC session (body: `agent_id`, `ui_type`, `grace_period`, `session_ttl`, `initial_message`, `metadata`). Returns a `session_token`
`POST`	`/api/webrtc/session/connect`	Exchange a `session_token` for LiveKit credentials
`POST`	`/api/webrtc/session/disconnect`	End a session (`explicit_end: true` skips the reconnection grace period)
`GET`	`/api/webrtc/session/status/{session_token}`	Session status
`WS`	`/api/webrtc/session/ws/{session_token}`	Session events (`agent_ready`, `agent_timeout`, `session_ended`)
`GET`	`/api/live-transcripts/history/{call_id}`, `/status/{call_id}`, `/url/{call_id}`	Live-caption history, status and a fresh signed URL for a call
`GET`	`/api/live-transcripts/stream/{call_id}` (SSE), `/ws/{call_id}` (WebSocket)	Live captions, see Live Captions

Overview

Campaigns

Agents

Calls

Overview

Authentication

Endpoints without an API key

Base URL

Errors

API Version

Agent Builder

Call Management

Other Endpoints

​Overview

​Authentication

​Endpoints without an API key

​Base URL

​Errors

​API Version

​Agent Builder

​Call Management

​Other Endpoints

Overview

Authentication

Endpoints without an API key

Base URL

Errors

API Version

Agent Builder

Call Management

Other Endpoints