API reference

REST API.

Everything the dashboard does, you can do over HTTPS. The full schema with request and response shapes lives at the live OpenAPI spec — this page is the orientation map.

Base URL

https://api.reasonvoice.ai

All endpoints are HTTPS. There's no versioned prefix — breaking changes go through deprecation announcements rather than path bumps; small additive changes ship continuously.

Authentication

Two key types depending on context:

Publishable

reva_…

Used by the chat widget and any browser-side code. Origin- locked server-side: a publishable key only works on the domains you whitelist on its widget. Safe to ship in client HTML.

Secret

sk_live_…

Server-to-server. Sends with Authorization: Bearer sk_live_…. Never embed these in browser code or commit them to source control. We rotate immediately if a leak is reported.

Endpoint groups

Each group is mounted at the prefix shown. Full route lists, parameter types, and example responses are in the OpenAPI spec.

Agents

/api/agents

Create, list, update, delete agents. Each agent encapsulates a system prompt, voice, language, knowledge base, and tool toggles.

Chat

/api/chat

Send messages to an agent and receive streaming SSE responses. Used by the widget; available directly for custom UIs.

Widgets

/api/widgets

Manage chat widgets (create, list, embed config, public config, embed code generator, analytics).

Telephony

/api/telephony

Provision phone numbers (managed Telnyx or BYOP Twilio/Telnyx), list area codes, attach numbers to agents, view inbound + outbound call history.

Calls

/api/calls

List and inspect calls — transcripts, tools invoked, duration, cost, recordings (when enabled).

CRM

/api/crm

Per-agent CRM integrations. Configure Odoo / HubSpot / custom REST. Fields, mappings, activity logs.

Integrations

/api/integrations

Connect external services (Stripe, Google Calendar, Slack, etc.). Stored encrypted and scoped to your account.

Knowledge base

/api/knowledge-base

Upload documents (PDF, DOCX, MD, etc.), trigger reindex, semantic search. Bypassed when the agent has no KB attached.

Subscriptions + billing

/api/subscriptions

Plan status, usage meters (minutes, messages, agents), upgrade flow. Backed by Stripe Billing.

Webhooks

/api/webhooks

Inbound webhook receiver for carrier events (Telnyx, Twilio) and Stripe billing events.

Tasks + workflows

/api/tasks · /api/dynamic-workflows · /api/workflow-templates

Schedule background jobs (outbound campaigns, follow-ups, post-call processing). DAG-shaped workflows for multi-step flows.

Teams

/api/teams

Invite members, set roles, manage seats.

Tracking

/api/tracking

Per-agent and per-call analytics events. Powers the dashboard charts and can be exported to your own warehouse.

Marketing (public)

/api/marketing

Public endpoints used by reasonvoice.ai itself — demo-call requests, public stats. Rate-limited per IP + phone.

Live OpenAPI spec

The complete, always-current spec is generated from the FastAPI decorators on every deploy. Use it for:

Generating typed clients (TS, Python, Go, etc.)
Browsing exact request/response schemas
Trying calls in the in-browser playground

Open the spec

Rate limits

Per-account: 100 requests/second sustained, 200/second burst. Per-IP on public endpoints (e.g. /api/marketing/demo-call): 5 per hour, 20 per day. When you hit a limit you'll get a 429 with a Retry-After header.

Errors

We return JSON error bodies with a detail string and, where useful, a code for programmatic handling.

{
  "detail": "Widget not found or not active",
  "code": "widget_not_found"
}