Skip to main content
Docs menu: Knowledge bases

Guides

Knowledge bases

Upload your documents to a knowledge base and attach it to an agent, so the agent can answer from them.

A knowledge base is a set of documents an agent can search while it answers: policies, service areas, price lists, FAQs. You manage them in the portal under Knowledge Base, or through the API as below. The same knowledge base can be attached to several agents.

Create a knowledge base

curl -X POST "https://api.telvana.com/knowledge-bases" \
  -H "x-api-key: $TELVANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Rider policies",
    "description": "Cancellation, no-show and wheelchair policies for riders"
  }'

Both fields are required, and names are unique within a workspace. The response's data.id is the knowledge base's id.

Upload documents

Send one file per request as multipart/form-data:

curl -X POST "https://api.telvana.com/knowledge-bases/<knowledgeBaseId>/documents" \
  -H "x-api-key: $TELVANA_API_KEY" \
  -F "file=@./rider-policies.pdf"

Telvana accepts PDF, DOCX, TXT, MD, CSV and JSON files up to 50 MB, judged by the file extension. It reads the text, splits it into passages and indexes them before it answers, so a large file can take a while. The document in the response ends in one of two states:

  • COMPLETED, with chunkCount set to the number of passages indexed.
  • FAILED, with an errorMessage. The most common cause is a file with no extractable text, such as a scanned PDF. Run it through OCR, or export the text, and upload it again.

A failed document stays in the list until you delete it.

Attach knowledge bases to an agent

curl -X PUT "https://api.telvana.com/agents/<agentId>/knowledge-bases" \
  -H "x-api-key: $TELVANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "knowledgeBaseIds": ["<knowledgeBaseId>", "<anotherKnowledgeBaseId>"] }'

The list replaces the agent's whole set, so include every knowledge base the agent should keep. An empty list detaches them all. GET on the same path shows what's attached now.

Keep documents current

There's no endpoint that replaces a document's contents. To update one, upload the new version and then delete the old one:

curl -X DELETE "https://api.telvana.com/knowledge-bases/documents/<documentId>" \
  -H "x-api-key: $TELVANA_API_KEY"

Deleting a document removes its file and its indexed passages. Deleting a whole knowledge base, with DELETE /knowledge-bases/<knowledgeBaseId>, removes it from every agent it was attached to, along with all of its documents.

Write documents the agent can use

The agent finds passages by meaning, then answers from the best matches. A few habits help it find the right ones:

  • Keep one topic per section, under a heading that names it, such as "Cancellations" or "Service area".
  • Write answers in full sentences rather than fragments or tables of codes.
  • Remove outdated versions, so two documents don't give different answers to the same question.