Every call the platform handles is reachable over a REST API, and every call event can be pushed to your systems by webhook. Authentication is a bearer token issued from the portal; all responses are JSON.
Base URL https://api.kwinova.com/api/v1
What you can call
| Area | Endpoints | What it does | Status |
|---|---|---|---|
| Calls | GET /calls · GET /calls/{id} · GET /calls/{id}/transcript |
List and filter calls, read a single call with its duration, outcome and per-turn latency, and pull the full transcript turn by turn. | Available |
| Recordings | GET /records |
The recording file for a call, with its timestamp and duration. Playback and download are also available in the portal. | Available |
| Trunks & numbers | GET /trunks · POST /trunks · PATCH /trunks/{id} |
Provision SIP trunks per realm, set priority and capacity, and manage the numbers attached to them. | Available |
| Call flows | GET /flows · PUT /flows/{id} |
Read and replace a flow document. Flows are validated on write, so a dead end or an unreachable node is refused rather than published. | Available |
| Schedules | GET /schedules · POST /schedules |
Time-of-day, weekday and holiday routing rules. | Available |
| Knowledge search | POST /search |
Hybrid full-text and vector search across your uploaded documents. Search-only API keys are available for read access from other systems. | Available |
| Documents | GET /documents · POST /documents · DELETE /documents/{id} |
Upload, list and remove the documents the agent answers from, and check processing status. | Available |
| Providers | GET /providers · GET /providers/{type} |
Which speech and language providers are configured, the languages and voices each offers, and their current health. | Available |
| Health & metrics | GET /health · GET /metrics |
Component health, active call counts and uptime. Metrics are exposed in Prometheus format. | Available |
| Assistants | POST /assistants · GET /assistants/{id} · PATCH · versions · rollback |
Named assistant objects — instructions, greeting, voice, outcomes and knowledge scope — with versioning and roll-back. | In design |
| AI session control | POST /calls/{id}/ai/start · /ai/cancel · GET /ai/status |
Start, cancel and inspect the AI session on a call in progress, including the current turn and live provider state. | In design |
Calling your systems from a conversation
The API above is how your software talks to Kwinova. The more interesting direction is the other one: during a live call, the AI agent can call your endpoints as tools — look up an order, move an appointment, raise a ticket — and read the real answer back to the caller before the call ends. Each tool has its own timeout and fallback, so a slow API delays an answer rather than hanging the call.
Webhooks
Call started, call ended, outcome recorded, recording ready and transcript ready can all be delivered to an endpoint you own. Campaign calls can also be triggered in the other direction — post to the call-by-webhook endpoint and the platform dials, runs the flow and posts the outcome back.
Errors and limits
Errors return a JSON body with a stable code, a human-readable message and a details object. Standard HTTP status codes apply — 400 invalid request, 401 unauthorised, 403 forbidden, 404 not found, 429 rate limited, 503 unavailable.
Getting a token
Tokens are issued per company from the portal, with a read-only variant for search. Ask us and we will set up a sandbox realm with a test number so you can build against something real before you go live.