API Documentation

Status	Code	Description
`401`	`UNAUTHORIZED`	Missing `X-API-Key` header
`401`	`UNAUTHORIZED`	Invalid or deactivated API key

Plan	Requests / Minute
Free	60
Professional	300
Enterprise	1,000

Header	Description
`X-RateLimit-Limit`	Max requests per minute for your plan
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

HTTP	Code	Description
400	`INVALID_REQUEST`	Bad input, missing required fields, validation failure
401	`UNAUTHORIZED`	Missing or invalid API key
403	`FORBIDDEN`	Valid key but insufficient permissions (e.g., project mismatch)
404	`NOT_FOUND`	Resource does not exist or has been deleted
409	`CONFLICT`	Duplicate resource or conflicting state
429	`QUOTA_EXCEEDED`	Plan quota reached for this resource type
429	`RATE_LIMITED`	Too many requests — slow down
500	`INTERNAL_ERROR`	Unexpected server error

GET /api/v1/quota

Check remaining quota

Returns per-resource quota breakdown for the project owner's plan.

Example Response

{
  "plan": "professional",
  "plan_display": "Professional",
  "quotas": {
    "projects":        { "limit": 10, "used": 3, "remaining": 7 },
    "agents":          { "limit": 50, "used": 12, "remaining": 38 },
    "knowledge_bases": { "limit": 20, "used": 4, "remaining": 16 },
    "sip_configs":     { "limit": 10, "used": 2, "remaining": 8 },
    "webhook_configs": { "limit": 10, "used": 3, "remaining": 7 },
    "team_members":    { "limit": 10, "used": 1, "remaining": 9 }
  }
}

Quota-Protected Endpoints

Endpoint	Quota Type
`POST /api/v1/rooms`	`rooms`
`POST /api/v1/token`	`sessions`
`POST /api/v1/rooms/:roomName/recordings/start`	`recordings`
`POST /api/v1/sip/dial`	`sip_configs`
`POST /api/v1/knowledge-bases`	`knowledge_bases`

When quota is exceeded, the endpoint returns 429 with code QUOTA_EXCEEDED including current usage and the upgrade URL.

cURL

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

Try It

GET /api/v1/usage

Get usage / cost data

Returns aggregated usage costs for your project.

Query Parameters

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

Example Response

{
  "period": "30d",
  "group_by": "day",
  "totals": {
    "cost_usd": 14.52,
    "input_tokens": 1250000,
    "output_tokens": 310000,
    "audio_minutes": 85.3,
    "tts_characters": 42000,
    "api_calls": 1240
  },
  "breakdown": [
    { "period": "2026-03-31", "cost": 2.10, "llm_cost": 1.80, "stt_cost": 0.20, "tts_cost": 0.10, "calls": 85 }
  ]
}

cURL

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

Try It

period

group_by

POST /api/v1/token

Generate a LiveKit room token

Generate a LiveKit token to join a room. Optionally dispatches one or more AI agents. Quota: sessions

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": "eyJhbGciOi...",
  "room": "proj_my-room",
  "wsUrl": "wss://livekit.ai0.dev",
  "agents_dispatched": [1]
}

Error Cases

Status	Code	When
400	`INVALID_REQUEST`	Missing `identity` or `room`
429	`QUOTA_EXCEEDED`	Session limit reached

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

POST /api/v1/rooms

Create a room

Create a new LiveKit room for your project. Quota: rooms

Request Body

Field	Type	Required	Description
`name`	string	Yes	Room name (auto-prefixed)
`empty_timeout`	number	No	Seconds before empty room closes (default 300)
`max_participants`	number	No	Max participants (0 = unlimited)
`metadata`	string	No	Room metadata

Example Response

{
  "success": true,
  "room": {
    "name": "my-room",
    "fullName": "proj_my-room",
    "sid": "RM_abc123",
    "emptyTimeout": 300,
    "maxParticipants": 0,
    "creationTime": 1711900000
  }
}

cURL

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

Try It

name *

empty_timeout

GET /api/v1/rooms

List active rooms

Returns all active LiveKit rooms for your project.

Example Response

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

cURL

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

Try It

GET /api/v1/rooms/:roomName

Room detail

Get details for a specific room including participants. Returns DB data for closed rooms.

Example Response

{
  "room": {
    "name": "my-room",
    "fullName": "proj_my-room",
    "sid": "RM_abc123",
    "status": "active",
    "numParticipants": 2,
    "maxParticipants": 0,
    "createdAt": 1711900000,
    "participants": [
      { "identity": "user1", "name": "User", "joinedAt": 1711900010 }
    ]
  }
}

cURL

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

Try It

roomName *

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

List participants in a room

Returns all current participants in a room with track info.

Example Response

{
  "participants": [
    {
      "identity": "user1",
      "name": "User",
      "state": "ACTIVE",
      "joinedAt": 1711900010,
      "tracks": [...]
    }
  ]
}

cURL

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

DELETE /api/v1/rooms/:roomName

Close / delete a room

Close a room in LiveKit and mark it as closed in the database. All participants are disconnected.

Example Response

{ "success": true, "message": "Room closed" }

cURL

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

POST /api/v1/rooms/:roomName/kick/:identity

Kick a participant

Remove a specific participant from a room by their identity.

Path Parameters

Param	Description
`roomName`	Room name (without project prefix)
`identity`	Participant identity to remove

cURL

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

GET /api/v1/agents

List agents

Returns all agent configurations for your project.

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 agent tools

Returns the tool definitions configured for an agent.

Example Response

{
  "tools": [
    {
      "name": "search_kb",
      "description": "Search the knowledge base",
      "parameters": { ... }
    }
  ]
}

cURL

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

POST /api/v1/sessions

Create a session log

Start a new session log for a room. Usually called by the agent server when a conversation begins.

Request Body

Field	Type	Required	Description
`room_name`	string	Yes	Full room name (including prefix)
`agent_config_id`	number	No	Agent config handling this session
`caller_identity`	string	No	Identity of the calling participant
`session_type`	string	No	`voice` or `sip` (default: `voice`)
`metadata`	object	No	Arbitrary session metadata

Example Response

{
  "session": {
    "id": 42,
    "project_id": 1,
    "room_name": "proj_my-room",
    "status": "active",
    "session_type": "voice",
    "created_at": "2026-03-31T10:00:00Z"
  }
}

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","session_type":"voice"}'

GET /api/v1/sessions

List sessions (paginated)

Returns paginated session logs with filtering.

Query Parameters

Param	Type	Default	Description
`page`	number	1	Page number
`per_page`	number	25	Results per page
`status`	string	—	`active` or `completed`
`agent_config_id`	number	—	Filter by agent
`session_type`	string	—	`voice` or `sip`
`from`	date	—	Start date (ISO 8601)
`to`	date	—	End date (ISO 8601)

Example Response

{
  "sessions": [
    {
      "id": 42,
      "room_name": "proj_my-room",
      "agent_name": "Support Agent",
      "status": "completed",
      "session_type": "voice",
      "duration": 185,
      "message_count": 12,
      "started_at": "2026-03-31T10:00:00Z",
      "ended_at": "2026-03-31T10:03:05Z"
    }
  ],
  "total": 156,
  "page": 1,
  "total_pages": 7
}

cURL

curl "https://voxai.ai0.dev/api/v1/sessions?status=completed&per_page=10" \
  -H "X-API-Key: YOUR_KEY"

Try It

status

per_page

GET /api/v1/sessions/:sessionId/detail

Session detail with costs

Full session detail including agent info and cost breakdown by service type (LLM, STT, TTS).

Example Response

{
  "session": {
    "id": 42,
    "room_name": "proj_my-room",
    "agent_name": "Support Agent",
    "llm_provider": "openai",
    "llm_model": "gpt-4o",
    "status": "completed",
    "duration_seconds": 185,
    "message_count": 12,
    "started_at": "2026-03-31T10:00:00Z"
  },
  "costs": { "total": 0.045, "llm": 0.038, "stt": 0.005, "tts": 0.002 }
}

cURL

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

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

Add transcript entry

Add a transcript line to the active session for a room. Usually called by the agent server in real-time.

Request Body

Field	Type	Required	Description
`speaker`	string	Yes	`agent`, `user`, or `system`
`content`	string	Yes	Text content
`timestamp_ms`	number	No	Timestamp in milliseconds from session start
`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, I need help","timestamp_ms":5200}'

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

End a session

End the active session for a room. Duration is auto-calculated unless overridden.

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":"Customer asked about billing"}'

GET /api/v1/sessions/:sessionId/transcript

Get transcript as JSON

Returns the full transcript for a session as structured JSON.

Example Response

{
  "session_id": 42,
  "transcripts": [
    { "speaker": "user", "content": "Hello", "timestamp_ms": 0, "created_at": "..." },
    { "speaker": "agent", "content": "Hi! How can I help?", "timestamp_ms": 1200, "created_at": "..." }
  ]
}

cURL

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

GET /api/v1/sessions/:sessionId/transcript/text

Get transcript as plain text

Returns the transcript as formatted plain text with timestamps. Content-Type: text/plain.

Example Response

[00:00] User: Hello
[00:01] Agent: Hi! How can I help you today?
[00:05] User: I need to update my billing info

cURL

curl https://voxai.ai0.dev/api/v1/sessions/42/transcript/text \
  -H "X-API-Key: YOUR_KEY"

POST /api/v1/rooms/:roomName/recordings/start

Start recording

Start recording audio in a room via LiveKit Egress. Quota: recordings

Example Response

{
  "success": true,
  "recording": {
    "id": 7,
    "egress_id": "EG_abc123",
    "room_name": "proj_my-room",
    "format": "ogg",
    "status": "recording"
  }
}

cURL

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

POST /api/v1/rooms/:roomName/recordings/stop

Stop recording

Stop recording. Pass egress_id to stop a specific recording, or omit to stop all active recordings for the room.

Request Body

Field	Type	Required	Description
`egress_id`	string	No	Stop specific egress; stops all if omitted

cURL

curl -X POST https://voxai.ai0.dev/api/v1/rooms/my-room/recordings/stop \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"egress_id":"EG_abc123"}'

GET /api/v1/recordings

List recordings

List all recordings for your project with pagination and filters.

Query Parameters

Param	Type	Default	Description
`page`	number	1	Page number
`per_page`	number	25	Results per page
`room_name`	string	—	Filter by room name
`status`	string	—	Filter by status (`recording`, `completed`, `error`)

cURL

curl "https://voxai.ai0.dev/api/v1/recordings?status=completed" \
  -H "X-API-Key: YOUR_KEY"

Try It

GET /api/v1/recordings/:recordingId

Recording detail

Get full details for a specific recording.

Error Cases

Status	Code	When
404	`NOT_FOUND`	Recording does not exist
403	`FORBIDDEN`	Recording belongs to different project

cURL

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

GET /api/v1/recordings/:recordingId/download

Download recording file

Stream the recording audio file. Supports HTTP Range headers for seeking/streaming. Content types: audio/ogg, audio/mp4, audio/wav.

cURL

curl -o recording.ogg https://voxai.ai0.dev/api/v1/recordings/7/download \
  -H "X-API-Key: YOUR_KEY"

DELETE /api/v1/recordings/:recordingId

Delete a recording

Permanently delete a recording and its audio file from disk.

cURL

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

POST /api/v1/sip/dial

Initiate outbound call

Initiate an outbound SIP phone call. Creates a room, dispatches an agent, and dials the phone number. Quota: sip_configs

Request Body

Field	Type	Required	Description
`phone_number`	string	Yes	E.164 format (e.g., `+17751234567`)
`agent_config_id`	number	No	Agent to dispatch (default: first active)
`room_name`	string	No	Custom room name suffix
`caller_id`	string	No	Outbound caller ID
`metadata`	object	No	Call metadata

Example Response

{
  "success": true,
  "call": {
    "room_name": "outbound-call-1",
    "full_room_name": "proj_outbound-call-1",
    "phone_number": "+17751234567",
    "caller_id": "+18001234567",
    "trunk_id": "ST_abc123",
    "session_id": 55,
    "sip_participant_id": "PA_xyz"
  },
  "token": "eyJ...",
  "wsUrl": "wss://livekit.ai0.dev"
}

Error Cases

Status	Code	When
400	`INVALID_REQUEST`	Invalid phone number format
400	`INVALID_REQUEST`	No SIP trunk configured
429	`QUOTA_EXCEEDED`	SIP config quota reached

cURL

curl -X POST https://voxai.ai0.dev/api/v1/sip/dial \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"phone_number":"+17751234567"}'

Try It

phone_number *

agent_config_id

GET /api/v1/sip/trunks

List SIP trunks

Returns SIP trunk configurations for your project.

Example Response

{
  "trunks": [
    {
      "id": 1,
      "name": "Main Trunk",
      "phone_number": "+18001234567",
      "inbound_trunk_id": "ST_in123",
      "outbound_trunk_id": "ST_out456",
      "dispatch_rule_id": "SDR_abc"
    }
  ]
}

cURL

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

Try It

GET /api/v1/sip/configs

List SIP configurations

Full SIP configurations with agent assignments and call settings.

Example Response

{
  "configs": [
    {
      "id": 1,
      "name": "Inbound Line",
      "phone_number": "+18001234567",
      "agent_config_id": 3,
      "agent_name": "Support Agent",
      "dtmf_enabled": true,
      "max_call_duration": 1800,
      "created_at": "2026-03-28T14:00:00Z"
    }
  ]
}

cURL

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

POST /api/v1/knowledge-bases

Create knowledge base

Create a new knowledge base for RAG. Quota: knowledge_bases

Request Body

Field	Type	Required	Description
`name`	string	Yes	Knowledge base name
`description`	string	No	Description
`chunk_size`	number	No	Characters per chunk (default 500)
`chunk_overlap`	number	No	Overlap between chunks (default 50)

cURL

curl -X POST https://voxai.ai0.dev/api/v1/knowledge-bases \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"name":"FAQ","description":"Customer support FAQs","chunk_size":400}'

Try It

name *

description

GET /api/v1/knowledge-bases

List knowledge bases

Returns all knowledge bases for your project with chunk counts.

Example Response

{
  "knowledge_bases": [
    { "id": 1, "name": "FAQ", "description": "Support FAQs", "chunk_count": 42, "created_at": "..." }
  ]
}

cURL

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

Try It

GET /api/v1/knowledge-bases/:kbId

Knowledge base detail

Full details including indexing status and character counts.

Example Response

{
  "knowledge_base": {
    "id": 1,
    "name": "FAQ",
    "description": "Support FAQs",
    "chunk_size": 500,
    "chunk_overlap": 50,
    "chunk_count": 42,
    "total_chars": 18500,
    "indexing_status": "ready",
    "last_indexed_at": "2026-03-31T10:00:00Z",
    "created_at": "2026-03-28T14:00:00Z"
  }
}

cURL

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

DELETE /api/v1/knowledge-bases/:kbId

Delete knowledge base

Permanently delete a knowledge base and all its chunks/embeddings.

cURL

curl -X DELETE https://voxai.ai0.dev/api/v1/knowledge-bases/1 \
  -H "X-API-Key: YOUR_KEY"

POST /api/v1/knowledge-bases/:kbId/documents

Upload document

Upload a file to be chunked and embedded. Supports .txt, .md, .csv, .json. Max 10 MB. Use multipart/form-data with field name file.

Example Response

{ "success": true, "chunks_created": 15, "source_file": "faq.md" }

cURL

curl -X POST https://voxai.ai0.dev/api/v1/knowledge-bases/1/documents \
  -H "X-API-Key: YOUR_KEY" \
  -F "file=@faq.md"

POST /api/v1/knowledge-bases/:kbId/ingest

Ingest raw text

Ingest raw text content directly (no file upload needed). Text is chunked and embedded.

Request Body

Field	Type	Required	Description
`content`	string	Yes	Raw text to ingest
`source_name`	string	No	Source label (default: `api_ingest`)

cURL

curl -X POST https://voxai.ai0.dev/api/v1/knowledge-bases/1/ingest \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"content":"Your company was founded in 2020...","source_name":"about-page"}'

POST /api/v1/knowledge-bases/:kbId/reindex

Re-index all chunks

Regenerate embeddings for all chunks. Useful after changing the embedding model or updating chunk content.

Example Response

{ "success": true, "chunks_reindexed": 42 }

cURL

curl -X POST https://voxai.ai0.dev/api/v1/knowledge-bases/1/reindex \
  -H "X-API-Key: YOUR_KEY"

GET /api/v1/knowledge-bases/:kbId/chunks

List chunks (paginated)

List chunks for a knowledge base with pagination. Content is truncated to 200 chars.

Query Parameters

Param	Type	Default	Description
`page`	number	1	Page number
`per_page`	number	20	Results per page
`is_active`	boolean	—	Filter by active status

Example Response

{
  "chunks": [
    { "id": 1, "content": "Your company was founded...", "source": "about-page", "chunk_index": 0, "is_active": true }
  ],
  "total": 42,
  "page": 1,
  "total_pages": 3
}

cURL

curl "https://voxai.ai0.dev/api/v1/knowledge-bases/1/chunks?per_page=10" \
  -H "X-API-Key: YOUR_KEY"

PUT /api/v1/knowledge-bases/:kbId/chunks/:chunkId

Update chunk content

Update the text content of a specific chunk. The embedding is regenerated automatically.

Request Body

Field	Type	Required	Description
`content`	string	Yes	Updated chunk text

cURL

curl -X PUT https://voxai.ai0.dev/api/v1/knowledge-bases/1/chunks/5 \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"content":"Updated text content here"}'

DELETE /api/v1/knowledge-bases/:kbId/chunks/:chunkId

Delete a chunk

Permanently delete a chunk and its embedding.

cURL

curl -X DELETE https://voxai.ai0.dev/api/v1/knowledge-bases/1/chunks/5 \
  -H "X-API-Key: YOUR_KEY"

POST /api/v1/knowledge/search

RAG semantic search

Perform a semantic search across a knowledge base. Returns the most relevant chunks.

Request Body

Field	Type	Required	Description
`knowledge_base_id`	number	Yes	KB to search
`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":"What are your business hours?","top_k":3}'

Try It

knowledge_base_id *

query *

POST /api/v1/webhooks/test

Fire a test webhook event

Send a test event to all active webhook endpoints for your project. Useful for verifying your webhook receiver.

Request Body

Field	Type	Required	Description
`event_type`	string	No	Event type to simulate (default: `test`)
`payload`	object	No	Custom payload

cURL

curl -X POST https://voxai.ai0.dev/api/v1/webhooks/test \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"event_type":"test","payload":{"hello":"world"}}'

Try It

Webhook Event Types

Your webhook endpoints will receive these event types automatically:

Event	Triggered When
`room.started`	Room becomes active (LiveKit webhook)
`room.finished`	Room is closed
`participant.joined`	Someone joins a room
`participant.left`	Someone leaves a room
`track.published`	Audio/video track published
`track.unpublished`	Track removed
`session.started`	AI session begins
`session.ended`	AI session completes
`recording.started`	Recording begins
`recording.stopped`	Recording ends
`sip.call_initiated`	Outbound SIP call started
`sip.inbound_call`	Inbound SIP call received
`knowledge.document_uploaded`	Document ingested into KB
`knowledge.reindexed`	KB re-indexed
`egress.started`	Egress process started
`egress.ended`	Egress process completed
`test`	Manual test event

Webhook Payload Format

{
  "event_type": "session.started",
  "project_id": 1,
  "timestamp": "2026-03-31T10:00:00.000Z",
  "data": {
    "session_id": 42,
    "room_name": "proj_my-room",
    "agent_config_id": 3
  }
}

Signature Verification

Webhook requests include an X-Webhook-Signature header containing an HMAC-SHA256 signature of the request body using your webhook secret. Verify it to ensure the request is authentic.

Connection

Connect to the WebSocket endpoint with your API key for real-time monitoring:

wss://voxai.ai0.dev/ws/monitor?api_key=pk_your_key

Authentication is via api_key query parameter. Invalid keys are rejected with close code 4001.

Subscribe to Channels

After connecting, subscribe to channels by sending JSON messages:

// Subscribe to all room events
{ "action": "subscribe", "channel": "rooms" }

// Subscribe to a specific room
{ "action": "subscribe", "channel": "room:my-room" }

Event Types

Event	Data Fields
`room.created`	room_name, created_at
`room.closed`	room_name
`participant.joined`	room_name, identity, name, joined_at
`participant.left`	room_name, identity, reason
`transcript.new`	room_name, session_id, speaker, content, timestamp_ms
`recording.status`	room_name, recording_id, status
`call.status`	room_name, phone_number, status

JavaScript Example

var ws = new WebSocket('wss://voxai.ai0.dev/ws/monitor?api_key=YOUR_KEY');

ws.onopen = function() {
  ws.send(JSON.stringify({ action: 'subscribe', channel: 'rooms' }));
};

ws.onmessage = function(event) {
  var msg = JSON.parse(event.data);
  console.log(msg.type, msg.data);
  // e.g. "transcript.new" { room_name, speaker, content }
};

POST /api/v1/rooms/:roomName/send-data

Send data to room (whisper / broadcast)

Send data to all participants or specific ones (whisper). Useful for supervisor-to-agent messaging.

Request Body

Field	Type	Required	Description
`data`	string \| object	Yes	Data payload to send
`destination_identities`	string[]	No	Specific participants (omit for broadcast)
`topic`	string	No	Message topic/channel

cURL — Broadcast

curl -X POST https://voxai.ai0.dev/api/v1/rooms/my-room/send-data \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"data":"Hello everyone","topic":"chat"}'

cURL — Whisper

curl -X POST https://voxai.ai0.dev/api/v1/rooms/my-room/send-data \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"data":"Only you can see this","destination_identities":["agent-1"]}'

Try It

roomName *

data *

POST /api/v1/rooms/:roomName/participants/:identity

Update participant

Update a participant's metadata, permissions, or display name.

Request Body

Field	Type	Required	Description
`metadata`	string	No*	Participant metadata
`permission`	object	No*	`{ canPublish, canSubscribe }`
`name`	string	No*	Display name

* At least one field is required.

cURL

curl -X POST https://voxai.ai0.dev/api/v1/rooms/my-room/participants/user1 \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"permission":{"canPublish":false}}'

POST /api/v1/rooms/:roomName/participants/:identity/mute

Mute / unmute participant

Mute or unmute a participant's audio. Auto-detects the first audio track if track_sid is not provided.

Request Body

Field	Type	Required	Description
`muted`	boolean	Yes	`true` to mute, `false` to unmute
`track_sid`	string	No	Specific track SID (auto-detects audio if omitted)

cURL

curl -X POST https://voxai.ai0.dev/api/v1/rooms/my-room/participants/user1/mute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"muted":true}'

Node.js

var API_KEY = 'pk_your_key';
var BASE = 'https://voxai.ai0.dev/api/v1';

// Generate a token and join a room
async function joinRoom(identity, room) {
  var res = await fetch(BASE + '/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'X-API-Key': API_KEY },
    body: JSON.stringify({ identity: identity, room: room }),
  });
  return await res.json();
}

// List active rooms
async function listRooms() {
  var res = await fetch(BASE + '/rooms', {
    headers: { 'X-API-Key': API_KEY },
  });
  return await res.json();
}

// Initiate an outbound call
async function dialPhone(phoneNumber) {
  var res = await fetch(BASE + '/sip/dial', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'X-API-Key': API_KEY },
    body: JSON.stringify({ phone_number: phoneNumber }),
  });
  return await res.json();
}

// Search knowledge base
async function searchKB(kbId, query) {
  var res = await fetch(BASE + '/knowledge/search', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'X-API-Key': API_KEY },
    body: JSON.stringify({ knowledge_base_id: kbId, query: query, top_k: 5 }),
  });
  return await res.json();
}

Python

import requests

API_KEY = 'pk_your_key'
BASE = 'https://voxai.ai0.dev/api/v1'
HEADERS = {'X-API-Key': API_KEY, 'Content-Type': 'application/json'}

# Generate token
r = requests.post(f'{BASE}/token', json={'identity': 'user1', 'room': 'my-room'}, headers=HEADERS)
token_data = r.json()

# List rooms
rooms = requests.get(f'{BASE}/rooms', headers=HEADERS).json()

# Check quota
quota = requests.get(f'{BASE}/quota', headers=HEADERS).json()
print(f"Plan: {quota['plan']}, Rooms remaining: {quota['quotas']['projects']['remaining']}")

# Upload a document to knowledge base
with open('faq.md', 'rb') as f:
    r = requests.post(f'{BASE}/knowledge-bases/1/documents',
                       headers={'X-API-Key': API_KEY},
                       files={'file': f})
    print(f"Chunks created: {r.json()['chunks_created']}")

cURL Quick Reference

# Check quota
curl https://voxai.ai0.dev/api/v1/quota -H "X-API-Key: YOUR_KEY"

# Create room
curl -X POST https://voxai.ai0.dev/api/v1/rooms \
  -H "Content-Type: application/json" -H "X-API-Key: YOUR_KEY" \
  -d '{"name":"meeting-1"}'

# Generate token
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":"meeting-1"}'

# Start recording
curl -X POST https://voxai.ai0.dev/api/v1/rooms/meeting-1/recordings/start \
  -H "X-API-Key: YOUR_KEY"

# Dial a phone number
curl -X POST https://voxai.ai0.dev/api/v1/sip/dial \
  -H "Content-Type: application/json" -H "X-API-Key: YOUR_KEY" \
  -d '{"phone_number":"+17751234567"}'

# List sessions
curl "https://voxai.ai0.dev/api/v1/sessions?status=completed" \
  -H "X-API-Key: YOUR_KEY"

# Download transcript
curl https://voxai.ai0.dev/api/v1/sessions/42/transcript/text \
  -H "X-API-Key: YOUR_KEY"

API Documentation

Table of Contents

1. Authentication

API Key

Base URL

Authentication Errors

Try It — API Key

2. Rate Limits

Response Headers

When Rate Limited

3. Error Handling

Error Codes

4. Quota & Usage

Example Response

Quota-Protected Endpoints

cURL

Query Parameters

Example Response

cURL

5. Tokens

Request Body

Example Response

Error Cases

cURL

6. Rooms

Request Body

Example Response

cURL

Example Response

cURL

Example Response

cURL

Example Response

cURL

Example Response

cURL

Path Parameters

cURL

7. Agents

Example Response

cURL

Example Response

cURL

8. Sessions

Request Body

Example Response

cURL

Query Parameters

Example Response

cURL

Example Response

cURL

Request Body

cURL

Request Body

cURL

Example Response

cURL

Example Response

cURL

9. Recordings

Example Response

cURL

Request Body

cURL

Query Parameters

cURL

Error Cases

cURL

cURL

cURL

10. SIP / Telephony

Request Body

Example Response

Error Cases

cURL

Example Response

cURL

Example Response

cURL