Core resources

Calls

Start web (browser) calls, read call records, transcripts, recordings, the per-turn event timeline, and analytics. Outbound phone calls are started via the Phone numbers → dial endpoint.

Call lifecycle

A call moves through these statuses. Poll GET /calls/{id}, or subscribe to status-update server messages to be pushed the transitions.

• `queued` — the call record exists; nothing has been dialed yet.
• `ringing` — the assistant is ready and the far end is being reached. On an outbound call this is the whole ring window; on a web call it means the browser hasn't joined yet.
• `in_progress` — someone is actually on the line. This is the point answeredAt is stamped, and the only status that bills.
• `completed` — the call connected and ended normally.
• `no_answer` — nobody picked up. Never billed.
• `failed` — an infrastructure fault (SIP, network, or assistant error).
• `canceled` — aborted with POST /calls/{id}/cancel before it connected.

startedAt is when the assistant joined; `answeredAt` is when a human actually connected — and it is the billing signal. On an outbound call that never answered, startedAt is set and answeredAt is null, and durationSeconds counts the ring.

Why a call ended

endedReason is one of: completed, customer_hangup, agent_hangup, agent_hangup_phrase, transferred, silence_timeout, no_answer, busy, sip_failure, network_error, agent_error, max_duration, canceled, stale, unknown.

When the carrier rejects a dial, its own diagnosis (busy / no_answer) is authoritative and is what you receive — the assistant may separately have timed out against dead air, but that is not reported as the reason.

POST/calls calls:write

Start a web call

Create a browser call to an assistant. Returns a LiveKit room token + websocket URL to connect from the client.

Body

agentId*	uuid	Assistant to run.
metadata	object	Arbitrary metadata stored on the call.

bash

curl -X POST https://api.bolchoai.in/v1/calls -H "Authorization: Bearer $BOLCHO_API_KEY" -H "Content-Type: application/json" \
  -d '{ "agentId": "'$AGENT_ID'" }'

Response

json

{ "callId": "c1…", "room": "call_…", "token": "<livekit-jwt>", "wsUrl": "wss://…livekit.cloud" }

GET/calls calls:read

List calls

List calls, newest first, with rich filters.

Query parameters

agentId	uuid	Filter by assistant.
status	string	queued \| ringing \| in_progress \| completed \| failed \| no_answer \| canceled.
direction	string	inbound \| outbound \| web.
endedReason	string	Filter by how the call ended — see the lifecycle section for the full list.
success	boolean	true \| false — filter by success evaluation.
from	string	ISO date — calls on/after this time.
to	string	ISO date — calls on/before this time.
minCost	number	Minimum call cost in USD.
limit	number	Page size.
offset	number	Pagination offset.

bash

curl "https://api.bolchoai.in/v1/calls?limit=20&status=completed" -H "Authorization: Bearer $BOLCHO_API_KEY"

GET/calls/{id} calls:read

Get call

Full call record: status, end reason, duration, cost breakdown, summary, structured data, TTS-cache savings, and the transcript turns.

Path parameters

id*

uuid

Call id.

bash

curl https://api.bolchoai.in/v1/calls/$ID \
  -H "Authorization: Bearer $BOLCHO_API_KEY"

POST/calls/{id}/cancel calls:write

Cancel a call

Abort a call that hasn't finished — typically one still queued or ringing. Tears down the room, evicting the assistant and any phone leg. Returns 400 if the call already ended.

Path parameters

id*

uuid

Call id.

bash

curl -X POST https://api.bolchoai.in/v1/calls/$CALL_ID/cancel -H "Authorization: Bearer $BOLCHO_API_KEY"

Response

json

{ "id": "c1…", "status": "canceled", "endedReason": "canceled", "endedAt": "2026-08-02T09:14:22.104Z" }

GET/calls/{id}/events calls:read

Get event timeline

The ordered event stream for session replay — turn latencies, tool calls, speech events.

Path parameters

id*

uuid

Call id.

bash

curl https://api.bolchoai.in/v1/calls/$ID/events \
  -H "Authorization: Bearer $BOLCHO_API_KEY"

GET/calls/{id}/recording calls:read

Get recording URL

A short-lived signed URL to the call audio recording.

Path parameters

id*

uuid

Call id.

bash

curl https://api.bolchoai.in/v1/calls/$ID/recording \
  -H "Authorization: Bearer $BOLCHO_API_KEY"

Response

json

{ "url": "https://…?signature=…" }

GET/calls/analytics analytics:read

Analytics rollup

Daily time-series + totals: calls, minutes, cost, success rate, latency (avg/p95), TTS-cache savings, and outcome breakdown.

Query parameters

days	number	Window in days (default 14).
agentId	uuid	Scope the rollup to one assistant.

bash

curl https://api.bolchoai.in/v1/calls/analytics \
  -H "Authorization: Bearer $BOLCHO_API_KEY"