llms.txt
# 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
