# Bolcho API

> The Bolcho voice + chat AI REST API. All endpoints are versioned under /v1. Base URL: https://api.bolchoai.in/v1

Authenticate with an API key (vx_live_…) via `Authorization: Bearer $BOLCHO_API_KEY` or the `x-api-key` header.

## Get started

- [Introduction](http://localhost:3000/docs/introduction): The Bolcho API lets you build voice AND text AI products programmatically — create one assistant and run it as a phone/web voice agent or as a text chatbot. Create assistants, connect phone numbers, place and receive calls, attach knowledge and tools, embed a chat widget, and stream transcripts and analytics. Everything in the dashboard is available over a REST API.
- [Authentication](http://localhost:3000/docs/authentication): Authenticate every request with an API key. Create keys in the dashboard under API Keys (or via the Workspace API). Keys are prefixed vx_live_…, are workspace-scoped, and carry a set of permission scopes.
- [Quickstart](http://localhost:3000/docs/quickstart): Two common flows: start a web (browser) call with an assistant, or place an outbound phone call over your SIP trunk.
- [Run in Postman](http://localhost:3000/docs/postman): Import the entire Bolcho API into Postman in seconds and start firing live requests, every endpoint, grouped, with sample bodies and bearer auth pre-wired.
- [Errors & status codes](http://localhost:3000/docs/errors): The API uses standard HTTP status codes. Error responses are JSON with a message.

## Core resources

- [Assistants](http://localhost:3000/docs/assistants): An assistant (agent) is the voice AI persona: its prompt, model, voice, language, tools and knowledge. Edits create new versions; calls always run the published version.
  - GET /agents — List assistants
  - GET /agents/{id} — Get assistant
  - POST /agents — Create assistant
  - PATCH /agents/{id} — Update assistant
  - POST /agents/{id}/versions — Create a version
  - POST /agents/{id}/publish — Publish assistant
  - GET /agents/{id}/attachments — Get attachments
  - PUT /agents/{id}/tools — Attach tools
  - PUT /agents/{id}/knowledge — Attach knowledge
  - POST /agents/{id}/share — Create share link
  - DELETE /agents/{id}/share — Revoke share link
  - DELETE /agents/{id} — Delete assistant
- [Calls](http://localhost:3000/docs/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.
  - POST /calls — Start a web call
  - GET /calls — List calls
  - GET /calls/{id} — Get call
  - POST /calls/{id}/cancel — Cancel a call
  - GET /calls/{id}/events — Get event timeline
  - GET /calls/{id}/recording — Get recording URL
  - GET /calls/analytics — Analytics rollup
- [Knowledge bases](http://localhost:3000/docs/knowledge-bases): Give assistants retrieval over your documents and websites. Add sources, then attach a Query tool over them to an assistant. The agent calls the Query tool during calls to fetch grounded answers.
  - GET /knowledge-bases — List knowledge bases
  - POST /knowledge-bases — Create knowledge base
  - GET /knowledge-bases/{id}/documents — List documents
  - POST /knowledge-bases/{id}/documents — Add a document
  - POST /knowledge-bases/{id}/websites — Add a website
  - POST /knowledge-bases/{id}/search — Semantic search
- [Files](http://localhost:3000/docs/files): Upload standalone documents (PDF, DOCX, Markdown, TXT) that assistants can retrieve from — a flat, workspace-level store, separate from named knowledge bases. Files are chunked and embedded automatically.
  - GET /files — List files
  - POST /files — Upload a file
  - GET /files/{id}/download — Get download URL
  - DELETE /files/{id} — Delete file
- [Structured outputs](http://localhost:3000/docs/structured-outputs): Reusable JSON schemas the assistant extracts from a conversation — capture fields like appointment date, order id, or qualification status as structured data on the call record.
  - GET /structured-outputs — List schemas
  - POST /structured-outputs — Create schema
  - PATCH /structured-outputs/{id} — Update schema
  - DELETE /structured-outputs/{id} — Delete schema
- [Tools](http://localhost:3000/docs/tools): Tools are functions the assistant can call mid-conversation (function calling) — look up an order, book a slot, hit your API, or search a knowledge base. Define a tool with a name, description, JSON-schema parameters and a type-specific config, then attach it to an assistant.
  - GET /tools — List tools
  - POST /tools — Create tool
  - PATCH /tools/{id} — Update tool
  - POST /tools/{id}/invoke — Test invoke
  - DELETE /tools/{id} — Delete tool
- [Contacts](http://localhost:3000/docs/contacts): Customers your assistants have spoken with, keyed by phone number. A contact records identity and call history only — assistants are never given remembered facts about a caller. To personalise a call, pass what you know with `variableValues` when you dial.
  - GET /contacts — List contacts
  - GET /contacts/{id} — Get contact
- [Human handoff](http://localhost:3000/docs/handoff): Everything that happens after a chatbot escalates to a person: who is on duty, who gets the conversation, how long the customer waits, and what the operator can do with it. Built so another application — a CRM, a helpdesk, your own dashboard — can be the agent console while Bolcho runs the queue.
  - GET /inbox/changes — What changed since…
  - POST /inbox/operators/sync — Sync the operator roster
  - POST /inbox/operators/heartbeat — Heartbeat / set availability
  - GET /inbox/operators — List operators
  - DELETE /inbox/operators/{externalId} — Remove an operator
  - GET /inbox — List conversations
  - POST /inbox/{id}/claim — Claim a conversation
  - POST /inbox/{id}/release — Release back to the queue
  - POST /inbox/{id}/transfer — Transfer to a colleague
  - POST /inbox/{id}/reply — Reply to the customer
  - POST /inbox/{id}/resolve — Resolve
  - POST /inbox/{id}/reopen — Hand back to the bot
  - POST /inbox/{id}/notes — Add a private note
  - POST /inbox/{id}/tags — Add a tag
  - DELETE /inbox/{id}/tags/{tag} — Remove a tag
  - GET /inbox/{id}/timeline — Conversation timeline
  - GET /inbox/canned-responses — List saved replies
  - POST /inbox/canned-responses — Save a reply
  - DELETE /inbox/canned-responses/{id} — Delete a saved reply
  - POST /inbox/presence/{agentId} — Report presence (legacy)
- [Recordings](http://localhost:3000/docs/recordings): Upload your own call recordings — your team's calls, not your assistant's — and get the same analysis Bolcho runs on its own calls: sentiment, summary, key points, concerns, a lead score and any structured fields you have defined. Upload a batch, poll it while it processes, then read the aggregate or drill into a single call.
  - POST /recordings/batches — Upload a batch
  - GET /recordings/batches — List batches
  - GET /recordings/batches/{id} — Get a batch
  - GET /recordings/batches/{id}/recordings — List recordings in a batch
  - GET /recordings/{id} — Get a recording
  - POST /recordings/batches/{id}/retry — Retry failed recordings
  - DELETE /recordings/batches/{id} — Delete a batch
- [Voices](http://localhost:3000/docs/voices): Browse the text-to-speech voice catalog across providers, and preview a voice before assigning it to an assistant via config.ttsVoiceId.
  - GET /voices — List voices
  - POST /voices/preview — Preview a voice

## Telephony

- [SIP trunks](http://localhost:3000/docs/sip-trunks): Bring your own carrier over SIP. A trunk holds your carrier's gateways (termination/origination), auth, and advanced dialing options. Provisioning sets up the underlying LiveKit SIP trunks + dispatch rule. Every number you add to a trunk becomes a callable Phone number.
  - GET /telephony/trunks — List SIP trunks
  - POST /telephony/trunks — Create SIP trunk
  - PATCH /telephony/trunks/{id} — Update SIP trunk
  - POST /telephony/trunks/{id}/provision — Re-provision trunk
  - DELETE /telephony/trunks/{id} — Delete SIP trunk
- [Phone numbers](http://localhost:3000/docs/phone-numbers): Import DIDs (or PBX extensions) onto a SIP trunk, route inbound calls to an assistant, place outbound calls, and release numbers.
  - GET /telephony/numbers — List numbers
  - POST /telephony/numbers — Import a number
  - POST /telephony/numbers/{id}/route — Route to assistant
  - PATCH /telephony/numbers/{id} — Update number
  - DELETE /telephony/numbers/{id} — Release number
  - POST /telephony/dial — Place an outbound call
- [Managed numbers (Plivo)](http://localhost:3000/docs/managed-numbers): Get phone numbers without your own SIP carrier. Buy managed numbers through Plivo (KYC/compliance handled in-platform), or connect your own Plivo account (BYO) to import numbers you already own.
  - GET /telephony/plivo/account — Get Plivo account
  - POST /telephony/plivo/account — Connect BYO Plivo
  - DELETE /telephony/plivo/account — Disconnect BYO Plivo
  - GET /telephony/plivo/account/numbers — List BYO numbers
  - GET /telephony/plivo/search — Search numbers
  - POST /telephony/plivo/buy — Buy a managed number
  - POST /telephony/plivo/import — Import a BYO number
  - PATCH /telephony/plivo/numbers/{id} — Assign a number
  - DELETE /telephony/plivo/numbers/{id} — Release a number
  - GET /telephony/plivo/compliance — Get compliance status
  - POST /telephony/plivo/compliance/refresh — Refresh compliance
  - POST /telephony/plivo/compliance — Submit compliance docs
  - POST /telephony/plivo/dial — Place an outbound call

## Chat & widget

- [Chat (text)](http://localhost:3000/docs/chat): Run any assistant as a text chatbot — same brain (prompt, knowledge, tools) as voice, delivered as chat. Conversations are stored server-side; send a message and get a reply as JSON or as a token-by-token SSE stream. Replies use the assistant's Query/API tools automatically and return grounded citations.
  - POST /chat — One-shot chat
  - POST /conversations — Create conversation
  - GET /conversations — List conversations
  - GET /conversations/analytics — Chat analytics
  - GET /conversations/{id} — Get conversation
  - GET /conversations/{id}/messages — List messages
  - POST /conversations/{id}/messages — Send message
  - POST /conversations/{id}/resolve — Resolve conversation
  - POST /conversations/{id}/handoff — Flag for human
  - DELETE /conversations/{id} — Delete conversation
- [Public Chatbot API](http://localhost:3000/docs/public-chatbot): The browser-safe API that powers the embeddable chat widget. Authenticate with a publishable key (pk_live_…) in the x-voxa-public-key header — never put a secret API key in the browser.
  - GET /public/chatbot/config — Get widget config
  - POST /public/chatbot/conversations — Start a conversation
  - POST /public/chatbot/conversations/{id}/messages — Send a message
  - POST /public/chatbot/lead — Capture a lead
- [Publishable keys](http://localhost:3000/docs/publishable-keys): Browser-safe keys (pk_live_…) that let the chat widget talk to one assistant from allow-listed domains. Manage them per assistant. Unlike API keys, publishable keys are meant to ship in your website's HTML.
  - GET /agents/{id}/publishable-keys — List publishable keys
  - POST /agents/{id}/publishable-keys — Create publishable key
  - POST /agents/{id}/publishable-keys/{keyId} — Update publishable key
  - DELETE /agents/{id}/publishable-keys/{keyId} — Revoke publishable key
- [Widget config](http://localhost:3000/docs/widget-config): Branding, greeting, starter questions, and lead-capture settings for an assistant's chat widget. These drive what the Public Chatbot config endpoint returns.
  - GET /agents/{id}/widget — Get widget config
  - PUT /agents/{id}/widget — Update widget config

## Server Messages

- [Server Messages](http://localhost:3000/docs/server-messages): Each assistant can POST what happens during a call to its own server URL — call status, the end-of-call report, and tool calls. Configure it per assistant, so different assistants can talk to different backends.
  - GET /agents/{id}/server-messages/types — List message types
  - GET /agents/{id}/server-messages/deliveries — Delivery log
  - POST /agents/{id}/server-messages/test — Send test message

## Workspace

- [Workspace & members](http://localhost:3000/docs/workspace): Your workspace profile, subscription, prepaid credit balance, and team members.
  - GET /workspace — Get workspace
  - GET /workspace/members — List members
  - POST /workspace/members — Invite member
  - PATCH /workspace/members/{userId} — Change member role
  - DELETE /workspace/members/{userId} — Remove member
- [API keys](http://localhost:3000/docs/api-keys): Manage the keys that authenticate API requests. The full key value is shown once at creation — store it securely.
  - GET /workspace/api-keys — List API keys
  - POST /workspace/api-keys — Create API key
  - DELETE /workspace/api-keys/{id} — Revoke API key
- [Billing](http://localhost:3000/docs/billing): Read your subscription and usage, and start a checkout or credit top-up. Amounts are in INR; usage cost is metered in USD.
  - GET /billing/subscription — Get subscription
  - GET /billing/usage — Get usage
  - GET /billing/config — Get billing config
  - POST /billing/checkout — Create checkout
  - POST /billing/topup — Top up credits
- [Integrations](http://localhost:3000/docs/integrations): Connect provider API keys — LLM, STT, TTS, telephony, billing, and automation. Keys are stored encrypted; responses only ever return a masked hint.
  - GET /integrations — List integrations
  - PUT /integrations/{provider} — Connect integration
  - DELETE /integrations/{provider} — Disconnect integration