Knowledge base

An agent with no knowledge base answers from what the model happens to remember about your business, which is nothing. Attach one and it answers from your documents instead — searched on every turn, inside the same turn, without the caller waiting for it.

When you need one

The symptom is specific: the agent is confidently wrong about your prices, your policies, your opening hours or your product range. No amount of prompt-writing fixes that, because you are asking a model to recall something it never knew. If instead the agent is answering in the wrong order, that is a flow problem, and if it needs a fact only your database has — this caller's order status — that is a function.

Step 1 · Create a base

curl -s -X POST https://voice.sphoro.com/v1/knowledge_bases \
  -H "Authorization: Bearer $SPHORO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Clinic policies", "language": "en"}'

{
  "id": "kb_1e5ba0d984f7665b",
  "name": "Acme Clinic policies",
  "language": "en",
  "document_count": 0,
  "created_at": "2026-09-08T09:20:11Z"
}

Step 2 · Put documents in it

curl -s -X POST https://voice.sphoro.com/v1/knowledge_bases/$KB_ID/documents \
  -H "Authorization: Bearer $SPHORO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Cancellation policy",
    "text": "Appointments cancelled less than 24 hours before the slot are charged a late cancellation fee of 500 rupees. Cancellations more than 24 hours ahead are free."
  }'

curl -s -X POST https://voice.sphoro.com/v1/knowledge_bases/$KB_ID/documents \
  -H "Authorization: Bearer $SPHORO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://acme.example/policies/cancellations"}'

curl -s -X POST https://voice.sphoro.com/v1/knowledge_bases/$KB_ID/documents \
  -H "Authorization: Bearer $SPHORO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://acme.example/help", "max_pages": 200}'

# A PDF or DOCX, base64 in "content", with the real filename.
curl -s -X POST https://voice.sphoro.com/v1/knowledge_bases/$KB_ID/documents \
  -H "Authorization: Bearer $SPHORO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"filename\": \"handbook.pdf\",
    \"content\": \"$(base64 < handbook.pdf | tr -d '\n')\"
  }"

Ingestion is a queued job

The request answers 202 Accepted and the work happens on a worker — a two-hundred-page crawl is not something to hold an HTTP connection open for. Poll the document list until the documents appear, or subscribe to knowledge_base.document.ingested.

curl -s https://voice.sphoro.com/v1/knowledge_bases/$KB_ID/documents \
  -H "Authorization: Bearer $SPHORO_API_KEY"

What the extractors will and will not do

Each of these will otherwise surprise you at the worst possible moment.

Step 3 · Attach it to the agent

curl -s -X PATCH https://voice.sphoro.com/v1/agents/$AGENT_ID \
  -H "Authorization: Bearer $SPHORO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"knowledge_base_ids": ["'"$KB_ID"'"]}'

Step 4 · Check what it retrieves, before a caller does

Search the base directly with the question you are worried about. This is the single most useful thing on this page: it turns "the agent gave a wrong answer" into "the right chunk is not being retrieved" or "the right chunk is retrieved and the prompt ignored it", which are different problems with different fixes.

curl -s -X POST https://voice.sphoro.com/v1/knowledge_bases/$KB_ID/search \
  -H "Authorization: Bearer $SPHORO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "what happens if I cancel the day before", "top_k": 5}'

{
  "results": [
    {
      "text": "Cancellation policy › Late cancellations — Appointments cancelled less than 24 hours before the slot are charged a late cancellation fee of 500 rupees.",
      "title": "Cancellation policy",
      "section": "Late cancellations",
      "document_id": "doc_7c31f0a2",
      "score": 0.81,
      "vector_score": 0.78,
      "lexical_score": 0.86
    }
  ]
}

Both scores are returned because they fail differently. A high lexical_score with a low vector_score means the caller happened to use your document's words; the reverse means the meaning matched but the wording did not. A question that scores low on both is one your corpus does not answer, however confidently the agent replies.

How a document becomes an answer

document ──▶ extract ──▶ chunk ──▶ embed ──▶ index
                                                   │
caller's question ──▶ embed ──▶ search ──▶ rank ──▶ floor ──▶ token budget
                                                   │
                                                   ▼
                                     grounding block in the prompt

Chunking is structure-aware rather than a fixed character window: whole paragraphs, lists and tables are packed together up to a budget, sentences are never split, and a chunk resets at a heading so it cannot straddle two topics. Each chunk is then prefixed with its document title and section path — which is the step that matters most and is the easiest to underestimate. A chunk reading "₹500" is unmatchable by anybody; the same chunk stored as "Cancellation policy › Late cancellations — a late cancellation is charged ₹500" is found by somebody asking about cancellation fees.

Retrieval inside a live call

Grounding happens inside the turn, which puts it squarely inside the latency budget. Two consequences worth designing around:

• It is bounded. retrieval_timeout_ms caps it — 50 to 2000ms, under autonomy: "custom". See agent reference.
• It fails open. A knowledge base that is slow or unreachable costs the caller a less-grounded reply, never silence on a live call. This is deliberate: grounding improves an answer, it is not a precondition for one.

Writing documents that retrieve well

Keeping it current

curl -s -X DELETE https://voice.sphoro.com/v1/knowledge_bases/$KB_ID/documents/$DOC_ID \
  -H "Authorization: Bearer $SPHORO_API_KEY"

There is no in-place edit of a document: replace it by deleting and re-ingesting. Re-crawling a site adds documents rather than reconciling them, so a base fed by a nightly crawl wants the old documents removed first — otherwise last month's prices are still in there, still retrievable, and still perfectly confident.