API reference
API introduction
Base URL, authentication, conventions and the map of the reference.
Base URL
All examples use https://api.kshyamai.space. Replace it with the address of your deployment. Requests and responses are JSON (Content-Type: application/json) unless a page says otherwise: file uploads are multipart, CSV exports are text/csv, the setup assistant streams text/event-stream.
Authentication
Authorization: Bearer vk-0123456789abcdef0123456789abcdefAPI keys (vk-), sub-account keys (sa-) and session tokens (vs-) are all sent this way. See Authentication for roles.
Conventions
| Topic | Rule |
|---|---|
| Errors | {"error": <HTTP status>, "message": "..."} on every 4xx and 5xx. See Errors. |
| Ids | UUIDs. An id that belongs to another workspace answers 404. |
| Times | ISO 8601 in UTC with a Z suffix, for example 2026-11-05T09:30:00Z. |
| Phone numbers | E.164, for example +919876500000. |
| Money | Wallet balances are in major units of the deployment's currency. Costs on an execution and rates in the price book are in minor units (hundredths). Each page says which it uses. |
| Paging | page_number and page_size where a list is paged. See Pagination. |
| Retries | Idempotency-Key on the endpoints that create or spend. See Idempotency. |
| Tracing | X-Request-Id on every response. |
| Limits | Per-minute request limits. See Rate limits. |
| Body size | 2 MB by default; less for login and public forms; more for the upload routes. |
Machine-readable descriptions
A deployment serves two OpenAPI documents:
| Document | Covers |
|---|---|
GET /openapi.json | The core API. |
GET /openapi.sonic.json | The extensions. Every operation has a request and response schema, and the query parameters are read from the server code. |
This reference is written from those documents and checked against the server code. Where the two disagreed, the reference follows the code.
Core API
| Page | Resources |
|---|---|
| Agents | Create, read, update, delete and stop agents; webhook test; test chat |
| Calls | Place and stop a call |
| Executions | Call records, logs, webhook deliveries |
| Batches | CSV batches: create, schedule, stop, results |
| Knowledge bases | Upload and manage documents |
| Phone numbers | Search, buy, release, link to inbound |
| SIP trunks | Trunks and their numbers |
| Providers | Third-party credentials |
| Voices and models | Voice catalog, custom models, price estimate |
| Sub-accounts | Create and manage sub-accounts, usage |
| Account | The current workspace |
| Dispositions | Dispositions and extraction categories |
| Violations | Report and list violations |
| Workflows | Drafts, versions, validation, runs |
| Workflow campaigns | Campaigns, entries, reports |
| Workflow executions | One run of a workflow |
Extensions
| Page | Resources |
|---|---|
| Auth | Sign-up, login, two-factor, sessions, API keys |
| Team | Members, invitations, roles, security log |
| Billing | Balance, ledger, plans, invoices, top-ups |
| Compliance | Compliance settings, do-not-call list, registry check |
| Verified numbers | Verify recipient numbers with a code |
| Messaging | SMS and WhatsApp message log |
| Function tools | Catalog, validation, test |
| Graph agents | Graph validation |
| Leads | Website forms and the leads they create |
| Assistants | Ask and the setup assistant |
| Voice test | Browser voice test ticket |
| Operations | Health, readiness, dead-letter lists |
Not in this reference
Operator endpoints (/admin/..., /metrics), the development outboxes (/dev/...) and the engine's own callbacks (/engine/...) are for whoever runs the deployment, not for customers. The engine callbacks are described in Engine protocol.