Knowledge base

How it works

1. You create a knowledge base and add sources to it. Each source is processed in the background: Voxa extracts its text, splits it into passages of about 1,000 characters (each repeats the last 200 characters or so of the one before, so a fact split across a boundary is still found whole), and indexes them for semantic search.
2. You attach the knowledge base to one or more agents, in the agent’s LLM tab or with knowledge_base_ids.
3. During a call, the agent gets a built-in tool, search_knowledge_base. When the caller asks a factual question about your business, the LLM calls it with a short query. Voxa finds the closest passages across every knowledge base the agent has, and gives the LLM up to four of them with their source names.
4. The LLM answers from those passages. If nothing relevant is found, the tool says so and the agent tells the caller it doesn’t have that information rather than inventing an answer.

The search is semantic: “kya aap Sunday ko khule ho?” finds a passage that says “closed on Sundays”, even though no words match. Questions and documents can be in different languages.

Each search is recorded on the call’s timeline as a kb.search event (see Events) and as a tool turn in the transcript.

Sources and limits

Source	What is read	Limits
PDF file	The text of every page. Scanned pages (images of text) have no text and are not read; password-protected PDFs are refused.	5 MB and 100 pages per file
Text file (.txt, .md, .markdown)	The file as UTF-8 text. Markdown is kept as written.	10 MB per file
Pasted text	What you paste, with a title you choose.	500,000 characters
Web page	One page: its main text (scripts, navigation, headers and footers are dropped). HTML, plain text, Markdown and PDF URLs work. Links on the page are not followed: add each page you need.	5 MB per page, 15 s to answer, public addresses only

Limit	Default
Knowledge bases per workspace	20
Sources per knowledge base	50
Passages per knowledge base	3,000 (roughly 3 MB of text)
Knowledge bases per agent	10

A file’s type is checked from its contents, not its name or the browser’s claim. Web pages are fetched by Voxa’s server, so addresses on private networks (localhost, 10.x, 192.168.x, cloud metadata addresses and so on) are refused, also after redirects. Pages that need a login, or that build their text with JavaScript, may come out empty: paste the text instead.

Source status

status	Meaning
processing	Waiting for, or being read by, the background worker. Usually a few seconds; large PDFs take longer.
ready	Searchable. chunk_count is its number of passages.
failed	Not searchable. error says why, for example no text found in the PDF (scanned pages are not supported). Fix the source and add it again, or Re-process it.

Re-process reads a source again (a web page is fetched again, so use it when the page changed). Its old passages stay searchable until the new ones are ready.

Using it in an agent

In the console, open the agent, go to the LLM tab and tick the knowledge bases under Knowledge bases. Through the API, set knowledge_base_ids on the agent:

Field	Type	Default	Allowed	What it does
knowledge_base_ids	array of strings	[]	up to 10 ids of this workspace’s knowledge bases	The knowledge bases the agent answers from. Empty: no knowledge base.
knowledge_mode	string	"auto"	"auto", "search"	How the agent reads them: see How the agent reads a knowledge base.

curl -X PUT https://voxa.abhinavyadav.in/api/v1/agents/AGENT_ID \
  -H "X-API-Key: $VOXA_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Front desk", "system_prompt": "You are the receptionist of Sunrise Dental Clinic...", "knowledge_base_ids": ["kb_5f2c..."]}'

PUT replaces the whole configuration, so send every field you want to keep (or use the MCP update_agent tool, which merges).

How the agent reads a knowledge base

Whole text ("auto", the default). When all the agent’s knowledge bases together hold up to 30,000 characters (about 10 pages), the agent gets their whole text in its prompt when the call starts. It can’t miss a passage, and it answers without a search round trip. Most FAQs, price lists and policy pages fit. The call’s timeline shows a kb.inline event.

Search. Larger knowledge bases, or every knowledge base when knowledge_mode is "search", are searched: the agent calls the built-in search_knowledge_base tool with a question and gets the best 5 passages. Each search looks for the passages two ways at once and combines them:

• by meaning: embeddings of the question and of each passage (with its source’s name), so “do you work weekends” finds “open Monday to Saturday”;
• by keywords: the exact words, so names, codes and numbers like “Plan B”, “MRI” or “₹4,000” are found even when the meaning search ranks them low.

It searches both the agent’s question and what the caller actually said, so a detail the model left out of its question still counts.

Either way, Voxa adds an instruction to the prompt: answer factual questions about the business only from the knowledge base, use names, prices and numbers exactly as written, and say it doesn’t know when the knowledge base doesn’t cover it. You don’t need to write this yourself, but your prompt can add detail, for example “Always confirm the price before booking.”

search_knowledge_base is a reserved name: a tool of your own can’t use it.

A knowledge base that is attached to an agent can’t be deleted: the API answers 409 and names the agents. Remove it from those agents first, so no agent changes without a saved version.

Writing good source material

The agent can only answer what the passages say, and it reads them in the middle of a phone call. A few habits make a large difference:

• One topic per paragraph. Passages are cut at paragraph and sentence boundaries. “Root canal: ₹4,000 to ₹8,000 depending on the tooth.” finds better than a price table that spans pages.
• Questions and answers work well. An FAQ in Q: / A: form matches how callers ask.
• Say the subject in each paragraph. “Parking is free for patients for two hours” beats “It is free for two hours” (what is?).
• Keep facts current. Delete or re-process a source when it changes; old and new prices side by side confuse the agent.
• Leave out boilerplate. Navigation, legal footers and repeated headers dilute the search. Paste the useful part if a page is noisy.
• Keep instructions in the prompt. How the agent should behave belongs in the Agent tab prompt; the knowledge base is for facts.

Testing search

Open a knowledge base in the console and use Test search with a question a caller would ask. You see the passages a search would return, best first, with a meaning score from 0 to 1 and a keyword match mark. A passage is relevant, and given to the agent, when its meaning score is at least 0.5, or when it is a top keyword match scoring at least 0.35. The others are shown faded: the agent doesn’t get those. (This tests search; an agent in whole-text mode reads everything.) If the right passage scores low, rewrite it so it says the subject plainly, or split it into smaller paragraphs.

curl -X POST https://voxa.abhinavyadav.in/api/v1/knowledge-bases/kb_5f2c.../search \
  -H "X-API-Key: $VOXA_API_KEY" -H "Content-Type: application/json" \
  -d '{"query": "are you open on sunday", "limit": 3}'

{
  "results": [
    {
      "kb_id": "kb_5f2c...",
      "source_id": "ks_91ab...",
      "source_name": "clinic-faq.pdf",
      "text": "We are open Monday to Saturday from 9 am to 7 pm. The clinic is closed on Sundays.",
      "score": 0.71,
      "keyword": true,
      "relevant": true
    }
  ],
  "latency_ms": 412,
  "embed_ms": 398,
  "search_ms": 0.4,
  "min_score": 0.5
}

Most of the time is spent embedding the question (a call to Gemini); the search itself takes well under a millisecond. During a call the agent’s search usually takes a few hundred milliseconds, plus one more LLM request to answer with what it found.

API

All routes are under /api/v1/knowledge-bases. Reading needs the agents.view permission and changing needs agents.edit, so API keys can do both. Every change is in the audit log. See the API reference for every field.

Method and path	What it does
GET /knowledge-bases	List knowledge bases with their totals and the agents using each.
POST /knowledge-bases	Create one: {"name", "description"}.
GET /knowledge-bases/{id}	One knowledge base with its sources and their status.
PATCH /knowledge-bases/{id}	Change name or description.
DELETE /knowledge-bases/{id}	Delete it with its sources (409 while an agent uses it).
POST /knowledge-bases/{id}/sources/file	Upload a PDF, .txt or .md file (multipart, field file).
POST /knowledge-bases/{id}/sources/url	Add a web page: {"url", "name"} (name defaults to the page title).
POST /knowledge-bases/{id}/sources/text	Add pasted text: {"name", "text"}.
DELETE /knowledge-bases/{id}/sources/{source_id}	Delete a source and its passages.
POST /knowledge-bases/{id}/sources/{source_id}/reprocess	Read the source again.
POST /knowledge-bases/{id}/search	Test a search: {"query", "limit"} (limit 1 to 20, default 5).

Create a knowledge base and add an FAQ file, a page and some text:

curl -X POST https://voxa.abhinavyadav.in/api/v1/knowledge-bases \
  -H "X-API-Key: $VOXA_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Clinic FAQ", "description": "Timings, prices and policies"}'

curl -X POST https://voxa.abhinavyadav.in/api/v1/knowledge-bases/kb_5f2c.../sources/file \
  -H "X-API-Key: $VOXA_API_KEY" -F "file=@clinic-faq.pdf"

curl -X POST https://voxa.abhinavyadav.in/api/v1/knowledge-bases/kb_5f2c.../sources/url \
  -H "X-API-Key: $VOXA_API_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://sunrisedental.example.com/pricing"}'

curl -X POST https://voxa.abhinavyadav.in/api/v1/knowledge-bases/kb_5f2c.../sources/text \
  -H "X-API-Key: $VOXA_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Insurance", "text": "We accept Star Health and HDFC Ergo cards for cashless treatment."}'

Each add returns the source with "status": "processing":

{
  "id": "ks_91ab...",
  "kb_id": "kb_5f2c...",
  "kind": "file",
  "name": "clinic-faq.pdf",
  "url": "",
  "content_type": "application/pdf",
  "size": 182311,
  "status": "processing",
  "error": "",
  "chunk_count": 0,
  "characters": 0,
  "created_at": "2026-10-01T16:05:12+05:30",
  "processed_at": null,
  "created_by": "Asha"
}

Poll GET /api/v1/knowledge-bases/{id} until every source is ready or failed, then attach the knowledge base to an agent.

From an MCP client, list_knowledge_bases and search_knowledge_base are available (read-only). See MCP tools.