Voxa public API

Authentication

Create a private key under API keys in the console. The full key (sk_live_…, 40 characters) is shown once; only a SHA-256 hash is stored. Send it as a bearer token on every request:

Authorization: Bearer sk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Requests without a valid key get 401. Revoking a key in the console makes it fail immediately. A key may be limited to reading (see Key scopes). Only organization admins can create, change or revoke keys.

export VOXA_URL=http://localhost:3000
export VOXA_KEY=sk_live_...

curl -s "$VOXA_URL/api/v1/me" -H "Authorization: Bearer $VOXA_KEY"

Conventions

• Request bodies are JSON (content-type: application/json). Responses are JSON except the recording endpoint, which returns audio/wav (or a 302 to it on bucket storage, see Recording).
• List endpoints return { "data": [...], "count": n, "total": n, "hasMore": bool, "nextCursor": string | null } and page with limit and cursor (see Pagination).
• Create returns 201 with the full record; delete returns 204 with no body; other methods on a path return 405 with an Allow header.
• Every response carries permissive CORS headers (Access-Control-Allow-Origin: *) and answers OPTIONS preflights, so the API can also be called from a trusted browser environment that holds a key.
• Records are scoped to the organization the key belongs to. id, updatedAt and orgId are read-only; cost, latency and lat are computed by the server from the assistant's providers and ignored when sent.
• Timestamps are ISO-8601 strings in UTC.

Errors

Errors are JSON with an error message. Validation errors add a fields object keyed by field name.

{ "error": "Validation failed", "fields": { "name": "is required", "temperature": "must be a number" } }

Rate limits

Each key may make 120 requests per minute (a token bucket that refills continuously, two requests per second). Every response includes X-RateLimit-Limit and X-RateLimit-Remaining. When the bucket is empty the API answers 429 with a Retry-After header (seconds).

HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0

{ "error": "Rate limit of 120 requests per minute exceeded" }

Key scopes

Each key carries one or both scopes, chosen when it is created in the console (an admin can change them later):

A key created before scopes existed has both. A request whose method needs a scope the key lacks gets 403:

{ "error": "This API key does not have the \"write\" scope" }

GET /api/v1/me returns the key's effective scopes.

Test mode

Build and test without spending credits. When you create a key in the console, pick Test to get a test key (sk_test_…, same length and scopes as a live key). Every organization also has a test public key (pk_test_…, shown next to the public key on the API keys page) for the widget and the web SDK. A key's mode is fixed when it is created; keys created before test mode are live.

Calls started with test credentials are test calls:

• They are never charged: credits and the monthly usage do not change, and they are left out of usage reports, the cost breakdown and the console's Overview. The Calls page lists them under the Test calls filter with a Test tag, and the API returns them with "test": true.
• Their minutes count against the organization's test budget (60 minutes per month unless an admin changes it on the API keys page; the counter starts over every month). When it is used up, new test calls are refused with 402 and "reason": "test_budget".
• Each test call ends after 5 minutes at most (or sooner when the assistant's maximum duration is shorter).
• Video agents run in sandbox mode: a Lite agent always shows the sandbox avatar; a Full-mode agent must have sandbox mode on, else the start is refused with 403 and "reason": "test_mode_video".
• Test keys cannot drive phone numbers or outbound campaigns: such writes answer 403 with "reason": "test_mode_phone".
• Test keys read everything, create and edit assistants and start test web calls, but never make a change that cannot be taken back or that reaches live traffic: any DELETE, personal-data erasure (POST /api/v1/privacy/erase) and do-not-call list changes (/api/v1/dnc) answer 403 with "reason": "test_mode_scope". Use a live key for those.
• Webhooks of test calls go only to the organization's Test webhook URL (API keys page), never to the live server URLs of the organization or the assistant, and every payload carries "test": true. Without a test webhook URL test calls send no webhooks.

curl -s -X POST "$VOXA_URL/api/v1/web-calls" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "assistantId": "asst_7f3a91c2" }'

{ "token": "eyJhc3Npc3RhbnRJZCI6...", "url": "ws://localhost:3001", "expiresIn": 300, "assistantId": "asst_7f3a91c2", "test": true }

{ "error": "This organization used its test call minutes for this month. Raise the test budget on the API keys page, or use a live key.", "reason": "test_budget" }

Pagination

Every list endpoint pages the same way.

The response adds total (items matching across all pages), hasMore, and nextCursor (null on the last page). A cursor stays valid when the item it points at is deleted; a cursor this API did not issue gets 400.

curl -s "$VOXA_URL/api/v1/assistants?limit=2" -H "Authorization: Bearer $VOXA_KEY"
{ "data": [ ... ], "count": 2, "total": 5, "hasMore": true, "nextCursor": "eyJpZCI6ImFzc3RfYjIiLCJpIjoxfQ" }

curl -s "$VOXA_URL/api/v1/assistants?limit=2&cursor=eyJpZCI6ImFzc3RfYjIiLCJpIjoxfQ" -H "Authorization: Bearer $VOXA_KEY"

Assistants

An assistant is the full configuration of a voice agent: model, prompt, voice, transcriber, call rules and tools. The record has the same shape as the console's Assistant type; the fields most often set through the API are listed below.

curl -s "$VOXA_URL/api/v1/assistants" -H "Authorization: Bearer $VOXA_KEY"

{ "data": [ { "id": "asst_7f3a91c2", "name": "Riley — Front desk", "status": "Published", "provider": "OpenAI", "model": "gpt-4o", ... } ],
  "count": 4, "total": 4, "hasMore": false, "nextCursor": null }

curl -s -X POST "$VOXA_URL/api/v1/assistants" \
  -H "Authorization: Bearer $VOXA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Taylor — Bookings",
    "provider": "Anthropic",
    "model": "claude-sonnet-4",
    "firstMessage": "Hi, you have reached Acme Dental. How can I help?",
    "prompt": "You book, move and cancel appointments for Acme Dental.",
    "tools": { "book": true, "transfer": true }
  }'

curl -s "$VOXA_URL/api/v1/assistants/asst_7f3a91c2" -H "Authorization: Bearer $VOXA_KEY"

curl -s -X PATCH "$VOXA_URL/api/v1/assistants/asst_7f3a91c2" \
  -H "Authorization: Bearer $VOXA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "Published", "maxDuration": 15, "tools": { "query": true } }'

curl -s -X DELETE "$VOXA_URL/api/v1/assistants/asst_7f3a91c2" -H "Authorization: Bearer $VOXA_KEY" -i

Calls

A call record holds who called, which assistant answered, duration, cost, the end-of-call summary and extracted data; the single-call endpoint adds the transcript. recordingUrl is set when a recording exists and points at /api/v1/calls/{id}/recording.

A call made with a video agent also carries video: { "provider": "heygen", "mode": "lite" | "full", "videoAgentId", "avatarId", "avatarName", "sessionId"?, "sandbox"?, "error"? }. mode says who ran the conversation (lite: the assistant through the voice server, full: HeyGen's own speech, model and voice); error is set when the avatar could not start or dropped and a Lite call continued as audio. For a Full-mode call assistantId and asst name the video agent itself (there is no assistant), and data holds mode and avatar entries.

Calls are listed from the moment they start. status tells where a call is in its life; it is derived from reason and kind:

curl -s "$VOXA_URL/api/v1/calls?assistantId=asst_7f3a91c2&limit=20&since=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $VOXA_KEY"

{
  "data": [
    { "id": "call_9a1", "assistantId": "asst_7f3a91c2", "asst": "Riley — Front desk", "customer": "+1 415 555 0134",
      "type": "Inbound", "reason": "Booking", "kind": "ok", "status": "completed", "secs": 192, "startedAt": "2026-10-03T14:33:10.000Z",
      "costN": 0.21, "summary": "...", "data": [ { "k": "Appointment", "v": "Tue 10:30" } ], "evalPass": true,
      "recordingUrl": "/api/v1/calls/call_9a1/recording" }
  ],
  "count": 1, "total": 1, "hasMore": false, "nextCursor": null
}

curl -s "$VOXA_URL/api/v1/calls/call_9a1" -H "Authorization: Bearer $VOXA_KEY"

curl -sL "$VOXA_URL/api/v1/calls/call_9a1/recording" -H "Authorization: Bearer $VOXA_KEY" -o call_9a1.wav

curl -s -X POST "$VOXA_URL/api/v1/web-calls" \
  -H "Authorization: Bearer $VOXA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "assistantId": "asst_7f3a91c2", "customerId": "cus_8f2k1", "variableValues": { "name": "Sam", "phone": "+14155550177" } }'

{ "token": "eyJhc3Npc3RhbnRJZCI6...", "url": "ws://localhost:3001", "expiresIn": 300, "assistantId": "asst_7f3a91c2" }

curl -s "$VOXA_URL/api/video/agents/vide_a88d176f?publicKey=pk_..."

{ "id": "vide_a88d176f", "name": "Sam (Full mode sandbox)", "mode": "full", "sandbox": true, "avatarName": "Wayne (sandbox)", "interactivity": "conversational", "status": "Published" }

Resources

Lists of the other objects configured in the console, plus the campaign actions. Each list returns { "data": [...], "count", "total", "hasMore", "nextCursor" } and pages with limit and cursor.

curl -s "$VOXA_URL/api/v1/files" -H "Authorization: Bearer $VOXA_KEY"

curl -s "$VOXA_URL/api/v1/tools" -H "Authorization: Bearer $VOXA_KEY"

curl -s "$VOXA_URL/api/v1/numbers" -H "Authorization: Bearer $VOXA_KEY"

curl -s "$VOXA_URL/api/v1/campaigns" -H "Authorization: Bearer $VOXA_KEY"

curl -s -X POST "$VOXA_URL/api/v1/campaigns/camp_3c1/contacts" -H "Authorization: Bearer $VOXA_KEY" \
  -H "content-type: application/json" -d '{"contacts":[{"phone":"+14155550100","vars":{"name":"Ada"}}]}'

curl -s -X POST "$VOXA_URL/api/v1/campaigns/camp_3c1/start" -H "Authorization: Bearer $VOXA_KEY"

curl -s -X POST "$VOXA_URL/api/v1/dnc" -H "Authorization: Bearer $VOXA_KEY" \
  -H "content-type: application/json" -d '{"number":"+14155550100","reason":"Opted out by email"}'

curl -s "$VOXA_URL/api/v1/knowledge-bases" -H "Authorization: Bearer $VOXA_KEY"

{ "data": [ { "id": "kb_front", "name": "Front desk", "fileCount": 3 } ], "count": 1, "total": 1, "hasMore": false, "nextCursor": null }

curl -s "$VOXA_URL/api/v1/me" -H "Authorization: Bearer $VOXA_KEY"

{ "key": { "id": "keys_3f9c", "name": "Production server", "prefix": "sk_live_", "created": "Oct 4, 2026", "lastUsedAt": "2026-10-04T15:18:03.871Z", "scopes": ["read", "write"] },
  "org": { "id": "org_1", "name": "Acme Dental" } }

curl -s "$VOXA_URL/api/v1/analytics/summary?from=2026-10-01" -H "Authorization: Bearer $VOXA_KEY"

{ "from": "2026-10-01T00:00:00.000Z", "to": "2026-10-16T12:00:00.000Z", "assistantId": null, "testCalls": 3,
  "calls": 412, "finished": 410, "minutes": 1285.4, "avgDurationSec": 188, "cost": 154.25, "successRate": 93.2,
  "status": { "live": 2, "interrupted": 1, "completed": 371, "failed": 28, "transferred": 9, "voicemail": 1 },
  "byType": { "Inbound": 301, "Outbound": 88, "Web": 23 },
  "evaluation": { "evaluated": 390, "passed": 351, "passRate": 90 }, "sentiment": { "scored": 380, "avg": 0.41 },
  "topReasons": [{ "reason": "Customer ended call", "calls": 290 }],
  "assistants": [{ "id": "asst_7f3a91c2", "name": "Front desk", "calls": 300, "minutes": 960.2, "cost": 115.1 }] }

curl -s "$VOXA_URL/api/v1/logs?callId=call_123&level=warn,error" -H "Authorization: Bearer $VOXA_KEY"

{ "data": [{ "id": "log_9a1", "ts": "2026-10-16T10:00:04.120Z", "level": "warn", "kind": "event", "message": "call.tool_failed", "source": "voice", "context": { "callId": "call_123", "tool": "book" } }],
  "count": 1, "hasMore": false, "nextUntil": null }

Developer tools

Packages in the repository's packages/ folder build on this API. Each has its own README.

MCP server (@voxa/mcp)

Manage assistants from Claude, Cursor or any Model Context Protocol client: list, create, update and publish assistants, start test calls, read calls, analytics and logs, add campaign contacts and start campaigns. It runs locally over stdio with a secret key; the API enforces the key's scopes and test-key limits, and destructive tools (update_assistant, start_campaign) carry destructiveHint. Start with a test key.

claude mcp add voxa -e VOXA_API_KEY=sk_test_... -e VOXA_BASE_URL=$VOXA_URL -- npx -y @voxa/mcp

CLI (@voxa/cli)

voxa login stores the key in the OS config directory (readable by you only; never echoed). voxa assistants deploy -f assistants.yaml creates or updates assistants by id or name after showing a diff (--yes in CI); voxa calls list|get, voxa logs tail --call <id> and voxa test-call <assistant> (prints the web call URL).

Python (voxa)

Sync and asyncio clients on httpx with typed models, pagination (list_all()), one exception per error status (fields, reason, retry_after) and voxa.webhooks.construct_event() for signatures.

from voxa import Voxa
client = Voxa(api_key="sk_live_...", base_url="https://console.example.com")
call = client.web_calls.create("asst_7f3a91c2")

Mobile SDKs (preview)

React Native (@voxa/react-native, with a pluggable PCM audio module and a react-native-audio-api adapter), iOS (Swift Package, AVAudioEngine) and Android (Kotlin, AudioRecord / AudioTrack). They speak the web SDK's protocol: a token from POST /api/voice/token with the public key, or a ticket your server mints with POST /api/v1/web-calls (startWithTicket), then the voice WebSocket with 16 kHz PCM16 up and 24 kHz PCM16 down. Apps send no Origin: when the organization restricts allowed origins, configure the SDK's origin option.

Webhooks

Voxa POSTs JSON events about calls to the assistant's serverUrl and to the organization's server URL (Organization settings), when set. Destinations must be public http(s) URLs; private and internal addresses are skipped. Each event is tried up to 3 times (after 1 s and 3 s) until your endpoint answers 2xx; a 3xx or 4xx answer stops the retries, and redirects are not followed. Every attempt shows on the console's Webhooks log.

Every body has event, timestamp (ISO-8601) and assistantId, plus the event's fields. Requests carry these headers:

Event payloads

POST /your/webhook HTTP/1.1
content-type: application/json
x-voxa-event: analysis
x-voxa-timestamp: 1791043200
x-voxa-signature: sha256=5f1c0e...

{ "event": "analysis", "timestamp": "2026-10-03T14:40:00.000Z", "assistantId": "asst_7f3a91c2",
  "callId": "call_9a1", "summary": "Booked a cleaning for Tuesday 10:30.",
  "data": { "appointment": "Tue 10:30", "insurance": null }, "evaluation": { "type": "pass", "pass": true },
  "analyzedAt": "2026-10-03T14:39:58.120Z" }

Tool requests

When the assistant calls a custom tool (Function / API request tools on the console's Tools page), Voxa sends the tool's URL (or the assistant's server URL) a request with the headers x-voxa-event: tool-calls and x-voxa-tool. A POST tool gets the JSON body { "tool", "arguments", "callId", "assistantId", "orgId", "verified" }; a GET tool gets the arguments as query parameters followed by tool, callId, assistantId, orgId and verified (JSON), which an argument of the same name cannot replace. The response body (at most 2000 characters) is what the assistant is told.

verified is the caller's verified identity on this call, or null when the caller has not been verified: { "at" (ISO-8601), "method": "sms", "to" (masked, "•••0123"), "number" (E.164; absent on HIPAA calls), "source": "caller" | "contact" | "variables" }. arguments come from the model, which repeats what the caller says: bind account lookups and changes to verified.number, never to an account number, name or phone number in the arguments alone, and refuse a request whose verified is null when the action needs a verified caller (marking the tool "Requires a verified caller" keeps the assistant from calling it before verification, but your server is the one that must check). The code goes only to a number from a trusted source: the caller's own line on phone calls, or variables your server supplied (campaigns, outbound calls, POST /web-calls).

Verifying signatures

Each organization has its own signing secret: whsec_ followed by 32 letters and digits. It is shown, and can be rotated, on the console's API keys page. From a signed-in console session (header x-voxa-org), GET /api/keys/webhook-secret returns { "secret": "whsec_…" }, creating the secret on first use, and POST /api/keys/webhook-secret rotates it: the new secret signs every request from then on, so update your receiver right away. The platform secret configured on the server (WEBHOOK_SECRET) is only a fallback for organizations that never revealed or rotated theirs; without either, requests are sent unsigned.

1. Read the raw request body as bytes, before any JSON parsing.
2. Compute the hex HMAC-SHA256 of x-voxa-timestamp, a literal ., and the raw body, with your secret.
3. Compare it with the hex after sha256= in x-voxa-signature in constant time.
4. Reject requests whose timestamp is more than 5 minutes from your clock, so a captured request cannot be replayed later. Retries are signed again with a fresh timestamp; deduplicate on callId plus event if you need exactly-once handling.

import crypto from "node:crypto";

export function verifyVoxa(rawBody, headers, secret) {
  const ts = headers["x-voxa-timestamp"];
  const sig = (headers["x-voxa-signature"] || "").replace(/^sha256=/, "");
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(ts + "." + rawBody).digest("hex");
  const a = Buffer.from(sig, "hex"), b = Buffer.from(expected, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Automation: Zapier, Make, n8n

No app to install: automation platforms use REST hooks. A zap, scenario or workflow subscribes a URL to one event with an API key; Voxa POSTs each event there, signed like every webhook (x-voxa-signature, see Verifying signatures), with the same retries and retry queue. Turning the automation off unsubscribes it. Events: call.ended, booking.created, voicemail.received, campaign.finished, lead.created (payloads under Event payloads). Test calls never reach hooks. Admins see and remove subscriptions on the console's Providers page (Automation).

Actions an automation can take with the same key: add a contact to a campaign, start a campaign's calls, start a browser call, add a number to the do-not-call list, find calls and change an assistant. Use a live key with the scopes it needs; test keys cannot subscribe or dial.

curl -s -X POST "$VOXA_URL/api/v1/hooks" -H "Authorization: Bearer $VOXA_KEY" \
  -H "content-type: application/json" -d '{"event":"call.ended","url":"https://hooks.zapier.com/hooks/standard/123/abc/"}'
{ "id": "hook_4f1c9a0b2d3e5f6a7b8c9d0e", "event": "call.ended", "url": "https://hooks.zapier.com/hooks/standard/123/abc/", "createdAt": "2026-10-15T09:00:00.000Z" }

curl -s -X DELETE "$VOXA_URL/api/v1/hooks/hook_4f1c9a0b2d3e5f6a7b8c9d0e" -H "Authorization: Bearer $VOXA_KEY"

Setup examples

Zapier (a private app in the Zapier Developer Platform): authentication API Key sent as Authorization: Bearer {{bundle.authData.apiKey}}, tested with GET /api/v1/me. For each trigger choose REST Hook:

// performSubscribe
const r = await z.request({ method: "POST", url: `${bundle.authData.baseUrl}/api/v1/hooks`,
  body: { event: "call.ended", url: bundle.targetUrl } });
return r.data;                              // keeps { id } for the unsubscribe
// performUnsubscribe
await z.request({ method: "DELETE", url: `${bundle.authData.baseUrl}/api/v1/hooks/${bundle.subscribeData.id}` });
// perform (the delivered event)
return [bundle.cleanedRequest];
// performList (sample data while building the zap)
const calls = await z.request({ url: `${bundle.authData.baseUrl}/api/v1/calls?limit=3` });
return calls.data.data.map((c) => ({ callId: c.id, ...c }));

Actions: Add campaign contact calls POST /api/v1/campaigns/{id}/contacts; Start campaign calls POST /api/v1/campaigns/{id}/start.

Make: add a Webhooks, Custom webhook module, copy its address, and subscribe it once with an HTTP, Make a request module (or curl): POST /api/v1/hooks with the address as url. To stop, DELETE /api/v1/hooks?url=<the address>. Actions use HTTP, Make a request with the Authorization: Bearer header.

n8n: a Webhook node (method POST) gives a production URL; subscribe it with an HTTP Request node or curl as above. Verify the signature in a Code node with the raw body (turn on Raw Body on the Webhook node) and the function under Verifying signatures. Actions: HTTP Request nodes with a Header Auth credential (Authorization = Bearer sk_live_...).

Versioning

The path prefix is the version. Fields may be added to responses without notice; removing or renaming one, or changing an error shape, would ship as /api/v2.

Recent additions (no version change): REST hooks (/hooks) with the call.ended, booking.created, campaign.finished and lead.created events; campaign contacts and campaign start; the crm value of an assistant's tools; the video field on calls and the public video agent routes; the analysis, billing.threshold, suite.finished and report.ready webhooks; the signed-URL answer of GET /calls/{id}/recording on bucket storage; key scopes.