API Documentation

Export Collection — Download a ready-to-import Postman collection.

Download for Postman

Authentication

All requests require an X-API-Key header.

X-API-Key: your-project-api-key

Base URL

All endpoints are relative to:

https://voxai.ai0.dev/api/v1

Try It — API Key

Interactive

Enter your API key here to test endpoints directly from the browser.

POST /api/v1/token

Generate a LiveKit room token

Generate a LiveKit token to join a room. Optionally dispatches one or more agents.

Request Body

Field	Type	Required	Description
`identity`	string	Yes	User identity for the room
`room`	string	Yes	Room name (auto-prefixed with project prefix)
`agent_config_id`	number	No	Single agent to dispatch
`agent_config_ids`	number[]	No	Multiple agents to dispatch
`no_agent`	boolean	No	If true, no agent is dispatched
`grants`	object	No	Extra LiveKit grants

Example Response

{
  "token": "eyJ...",
  "room": "proj_my-room",
  "wsUrl": "wss://livekit.example.com",
  "agents_dispatched": [1]
}

cURL

curl -X POST https://voxai.ai0.dev/api/v1/token \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"identity":"user1","room":"my-room"}'

Try It

identity *

room *

agent_config_id

no_agent

Agents

GET /api/v1/agents

List agents for your project

Returns all agent configurations for the project associated with your API key.

Example Response

{
  "agents": [
    { "id": 1, "name": "Support Agent", "agent_type": "voice", "llm_provider": "openai", "llm_model": "gpt-4o", "is_active": true }
  ]
}

cURL

curl https://voxai.ai0.dev/api/v1/agents \
  -H "X-API-Key: YOUR_KEY"

Try It

GET /api/v1/agents/:agentId/tools

Get tool definitions for an agent

Returns the list of tool definitions configured for a specific agent.

Path Parameters

Param	Type	Description
`agentId`	number	The agent config ID

cURL

curl https://voxai.ai0.dev/api/v1/agents/1/tools \
  -H "X-API-Key: YOUR_KEY"

Try It

agentId *

Rooms

GET /api/v1/rooms

List active rooms

Returns all currently active LiveKit rooms for your project.

Example Response

{
  "rooms": [
    { "name": "my-room", "fullName": "proj_my-room", "numParticipants": 2, "createdAt": 1711800000 }
  ]
}

cURL

curl https://voxai.ai0.dev/api/v1/rooms \
  -H "X-API-Key: YOUR_KEY"

Try It

GET /api/v1/rooms/:roomName/participants

List room participants

Returns participants currently in a specific room.

Path Parameters

Param	Type	Description
`roomName`	string	Room name (without project prefix)

cURL

curl https://voxai.ai0.dev/api/v1/rooms/my-room/participants \
  -H "X-API-Key: YOUR_KEY"

Try It

roomName *

Sessions

POST /api/v1/sessions

Create a session log

Creates a new session log entry for tracking agent conversations.

Request Body

Field	Type	Required	Description
`room_name`	string	Yes	Room name for the session
`agent_config_id`	number	No	Agent config ID
`caller_identity`	string	No	Caller identity
`session_type`	string	No	"voice" or "sip" (default: "voice")
`metadata`	object	No	Arbitrary metadata

cURL

curl -X POST https://voxai.ai0.dev/api/v1/sessions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"room_name":"proj_my-room","caller_identity":"user1"}'

Try It

room_name *

caller_identity

session_type

agent_config_id

POST /api/v1/sessions/:roomName/transcript

Add transcript entry

Adds a transcript entry to an active session for a given room.

Request Body

Field	Type	Required	Description
`speaker`	string	Yes	"agent", "user", or "system"
`content`	string	Yes	Transcript text
`timestamp_ms`	number	No	Timestamp in milliseconds
`is_final`	boolean	No	Whether this is a final transcript (default true)

cURL

curl -X POST https://voxai.ai0.dev/api/v1/sessions/proj_my-room/transcript \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"speaker":"user","content":"Hello agent"}'

Try It

roomName *

speaker *

content *

POST /api/v1/sessions/:roomName/end

End a session

Ends an active session, marking it as completed.

Request Body

Field	Type	Required	Description
`summary`	string	No	Session summary text
`duration`	number	No	Override duration in seconds

cURL

curl -X POST https://voxai.ai0.dev/api/v1/sessions/proj_my-room/end \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"summary":"User asked about pricing"}'

Try It

roomName *

summary

duration (seconds)

Knowledge (RAG)

POST /api/v1/knowledge/search

Search a knowledge base

Performs a RAG (semantic) search against a knowledge base.

Request Body

Field	Type	Required	Description
`knowledge_base_id`	number	Yes	Knowledge base ID
`query`	string	Yes	Search query text
`top_k`	number	No	Number of results (default 5)

cURL

curl -X POST https://voxai.ai0.dev/api/v1/knowledge/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"knowledge_base_id":1,"query":"How do I reset password?"}'

Try It

knowledge_base_id *

top_k

query *

Usage & Costs

GET /api/v1/usage

Get usage and cost data

Returns usage and cost data for your project, with optional period and grouping.

Query Parameters

Param	Type	Default	Description
`period`	string	30d	"today", "7d", "30d", or "all"
`group_by`	string	day	"day", "model", "agent", or "service"

cURL

curl "https://voxai.ai0.dev/api/v1/usage?period=7d&group_by=model" \
  -H "X-API-Key: YOUR_KEY"

Try It

period

group_by

Secrets

GET /api/v1/projects/:projectId/secrets/:provider

Get decrypted secrets for a provider

Returns decrypted secrets for the specified provider. Used by agent servers at runtime.

Path Parameters

Param	Type	Description
`projectId`	number	Must match the project of your API key
`provider`	string	"openai", "deepgram", "elevenlabs", "cartesia", etc.

cURL

curl https://voxai.ai0.dev/api/v1/projects/1/secrets/openai \
  -H "X-API-Key: YOUR_KEY"

Try It

projectId *

provider *

Webhooks

Receiving Webhooks

LiveKit sends webhook events to POST /webhooks/livekit with content type application/webhook+json. Configure your LiveKit server to point to:

https://voxai.ai0.dev/webhooks/livekit

Events include: room_started, room_finished, participant_joined, participant_left, track_published, etc.