Reference
API reference
One page per resource#
Generated from the backend's published OpenAPI document — regenerate with npm run api:reference, and npm run test:contract fails when it drifts. Each page lists every operation with its door, parameters, request and response fields, declared errors, and a runnable curl example.
| Resource | Operations | What it is for |
|---|---|---|
| Projects API | 7 | A project is the isolation boundary: credentials, keys, agents, numbers, sessions and webhooks all belong to exactly one. |
| API keys | 3 | Project-scoped machine keys. |
| Provider accounts | 13 | Your own AI credentials, encrypted per project. |
| Agents API | 34 | An agent is the frozen configuration a call runs against: pipeline, prompt, language, limits and webhook. |
| Knowledge bases | 24 | Documents your agents answer from. |
| Chat API | 8 | Typed chats with an agent, from your web chat or your own app. |
| Chat channels | 12 | Connect a channel of your own to one of your agents, and the agent answers everyone who writes to it: a Telegram bot made with @BotFather (its webhook is set for you), or a WhatsApp number or Instagram professional account on your own Meta app (paste the response's webhook_url and meta.verify_token into the app's webhook settings). |
| Voice sessions | 10 | One session is one call. |
| Carriers and numbers | 22 | Bring your own telephony account. |
| Call lists | 40 | Upload people to call (CSV, Excel, a Google Sheet or JSON rows), pick an agent and a phone line, set calling hours and start. |
| Webhooks API | 10 | Signed, retried event delivery per project. |
| Billing API | 8 | A prepaid USD wallet per account. |
Every operation#
Projects API#
| Method | Path | Door | Scope |
|---|---|---|---|
GET | `/v2/project/retention` | project key | project:read |
GET | `/console/v2/projects/{project_id}/retention` | account session | — |
PUT | `/console/v2/projects/{project_id}/retention` | account session | — |
POST | `/console/v2/projects/{project_id}/stored-conversations/delete` | account session | — |
GET | `/v2/projects` | account session | — |
POST | `/v2/projects` | account session | — |
GET | `/v2/projects/{project_id}` | account session | — |
API keys#
| Method | Path | Door | Scope |
|---|---|---|---|
GET | `/v2/api-keys` | account session | — |
POST | `/v2/api-keys` | account session | — |
DELETE | `/v2/api-keys/{key_id}` | account session | — |
Provider accounts#
| Method | Path | Door | Scope |
|---|---|---|---|
GET | `/v2/provider-accounts` | project key | provider_account:read |
POST | `/v2/provider-accounts` | project key | provider_account:write |
DELETE | `/v2/provider-accounts/{account_id}` | project key | provider_account:write |
GET | `/v2/provider-accounts/{account_id}` | project key | provider_account:read |
POST | `/v2/provider-accounts/{account_id}/probe` | project key | provider_account:write |
POST | `/v2/provider-accounts/{account_id}/rotate` | project key | provider_account:write |
GET | `/console/v2/projects/{project_id}/provider-accounts` | account session | — |
POST | `/console/v2/projects/{project_id}/provider-accounts` | account session | — |
DELETE | `/console/v2/projects/{project_id}/provider-accounts/{account_id}` | account session | — |
GET | `/console/v2/projects/{project_id}/provider-accounts/{account_id}` | account session | — |
POST | `/console/v2/projects/{project_id}/provider-accounts/{account_id}/probe` | account session | — |
POST | `/console/v2/projects/{project_id}/provider-accounts/{account_id}/rotate` | account session | — |
GET | `/v2/provider-catalog` | account session | — |
Agents API#
Knowledge bases#
Chat API#
| Method | Path | Door | Scope |
|---|---|---|---|
GET | `/v2/chats` | project key | voice:read |
POST | `/v2/chats` | project key | voice:write |
GET | `/v2/chats/{chat_id}` | project key | voice:read |
POST | `/v2/chats/{chat_id}/messages` | project key | voice:write |
GET | `/console/v2/projects/{project_id}/chats` | account session | — |
POST | `/console/v2/projects/{project_id}/chats` | account session | — |
GET | `/console/v2/projects/{project_id}/chats/{chat_id}` | account session | — |
POST | `/console/v2/projects/{project_id}/chats/{chat_id}/messages` | account session | — |
Chat channels#
| Method | Path | Door | Scope |
|---|---|---|---|
GET | `/v2/chat-channels` | project key | channel:read |
POST | `/v2/chat-channels` | project key | channel:write |
DELETE | `/v2/chat-channels/{channel_id}` | project key | channel:write |
GET | `/v2/chat-channels/{channel_id}` | project key | channel:read |
PATCH | `/v2/chat-channels/{channel_id}` | project key | channel:write |
POST | `/v2/chat-channels/{channel_id}/check` | project key | channel:write |
GET | `/console/v2/projects/{project_id}/chat-channels` | account session | — |
POST | `/console/v2/projects/{project_id}/chat-channels` | account session | — |
DELETE | `/console/v2/projects/{project_id}/chat-channels/{channel_id}` | account session | — |
GET | `/console/v2/projects/{project_id}/chat-channels/{channel_id}` | account session | — |
PATCH | `/console/v2/projects/{project_id}/chat-channels/{channel_id}` | account session | — |
POST | `/console/v2/projects/{project_id}/chat-channels/{channel_id}/check` | account session | — |
Voice sessions#
| Method | Path | Door | Scope |
|---|---|---|---|
GET | `/v2/voice/sessions` | project key | voice:read |
POST | `/v2/voice/sessions` | project key | voice:write |
GET | `/v2/voice/sessions/{session_id}` | project key | voice:read |
GET | `/v2/voice/sessions/{session_id}/transcript` | project key | — |
POST | `/v2/voice/sessions/outbound` | project key | voice:write |
GET | `/console/v2/projects/{project_id}/voice/sessions` | account session | — |
POST | `/console/v2/projects/{project_id}/voice/sessions` | account session | — |
GET | `/console/v2/projects/{project_id}/voice/sessions/{session_id}` | account session | — |
GET | `/console/v2/projects/{project_id}/voice/sessions/{session_id}/transcript` | account session | — |
POST | `/console/v2/projects/{project_id}/voice/sessions/outbound` | account session | — |
Carriers and numbers#
Call lists#
Webhooks API#
| Method | Path | Door | Scope |
|---|---|---|---|
GET | `/v2/projects/{project_id}/webhooks` | project key | webhook:read |
POST | `/v2/projects/{project_id}/webhooks` | project key | webhook:write |
DELETE | `/v2/projects/{project_id}/webhooks/{endpoint_id}` | project key | webhook:write |
POST | `/v2/projects/{project_id}/webhooks/{endpoint_id}/test` | project key | webhook:write |
GET | `/v2/projects/{project_id}/webhooks/dead-letters` | project key | webhook:read |
GET | `/console/v2/projects/{project_id}/webhooks` | account session | — |
POST | `/console/v2/projects/{project_id}/webhooks` | account session | — |
DELETE | `/console/v2/projects/{project_id}/webhooks/{endpoint_id}` | account session | — |
POST | `/console/v2/projects/{project_id}/webhooks/{endpoint_id}/test` | account session | — |
GET | `/console/v2/projects/{project_id}/webhooks/dead-letters` | account session | — |
Billing API#
| Method | Path | Door | Scope |
|---|---|---|---|
PUT | `/console/v2/billing/currency` | account session | — |
GET | `/console/v2/billing/invoices` | account session | — |
GET | `/console/v2/billing/invoices/{invoice_id}.pdf` | account session | — |
GET | `/console/v2/billing/quote` | account session | — |
GET | `/console/v2/billing/rate` | account session | — |
GET | `/console/v2/billing/summary` | account session | — |
POST | `/console/v2/billing/topup` | account session | — |
GET | `/console/v2/billing/transactions` | account session | — |
Conventions#
- Origin:
https://api.developers.dvaarik.com. - Machine door:
X-Api-Key: $DVAARIK_API_KEY, from a trusted server only. - Account door:
Authorization: Bearer $DVAARIK_TOKEN, the console session. - Money is an integer nano-USD decimal string; parse it with
BigInt, neverNumber. - Every error body is
{ "detail": … }; see the errors page. - There is no SDK yet. The examples are curl,
fetch, andrequests. - To try a call without writing code, use the playground rather than pasting a key into a browser.
Use one project per boundary
Provider secrets stay encrypted and project API keys stay on your server.