Knowledge Bases

Create and manage knowledge bases, add sources, and connect them to chatbots.

A Knowledge Base (KB) is a collection of text sources that Sarufi uses to answer questions via retrieval-augmented generation (RAG). Sources can be plain text snippets or web pages that Sarufi reads and keeps up to date.

Once created, a KB is attached to one or more chatbots. When a user asks a question the chatbot's flow doesn't explicitly handle, the KB is searched for a relevant answer. See How answers are found.


List Knowledge Bases

Returns all KBs in the workspace.

GET /api/dev/v1/knowledge-bases
Authorization: Bearer <api-key>
curl -X GET https://developers.sarufi.io/api/dev/v1/knowledge-bases \
  -H "Authorization: Bearer <your-api-key>"

Response - 200 OK

{
  "items": [
    {
      "id": "01KAB...",
      "name": "Product FAQ",
      "description": "Frequently asked product questions",
      "source_count": 12,
      "status": "ready",
      "created_at": "2026-01-20T09:00:00Z"
    }
  ],
  "total": 3
}

Create Knowledge Base

POST /api/dev/v1/knowledge-bases
Authorization: Bearer <api-key>
Content-Type: application/json

Request Body

FieldTypeRequiredDescription
namestringyesDisplay name for the knowledge base.
descriptionstringnoOptional description of what this KB contains.
curl -X POST https://developers.sarufi.io/api/dev/v1/knowledge-bases \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product FAQ",
    "description": "Common product and pricing questions"
  }'

Response - 201 Created

{
  "id": "01KAB123...",
  "name": "Product FAQ",
  "description": "Common product and pricing questions",
  "source_count": 0,
  "status": "empty",
  "created_at": "2026-02-01T10:00:00Z"
}

Get / Update / Delete Knowledge Base

GET    /api/dev/v1/knowledge-bases/{kb_id}
PATCH  /api/dev/v1/knowledge-bases/{kb_id}
DELETE /api/dev/v1/knowledge-bases/{kb_id}
Authorization: Bearer <api-key>

PATCH accepts name and description. DELETE returns 204 No Content and removes all sources.


Sources

Sources are the individual pieces of content indexed in a KB.

List Sources

GET /api/dev/v1/knowledge-bases/{kb_id}/sources
Authorization: Bearer <api-key>
curl -X GET https://developers.sarufi.io/api/dev/v1/knowledge-bases/<kb-id>/sources \
  -H "Authorization: Bearer <your-api-key>"

Each entry is a Source object.


Add Text Source

Indexes a plain text document directly.

POST /api/dev/v1/knowledge-bases/{kb_id}/sources/text
Authorization: Bearer <api-key>
Content-Type: application/json

Request Body

FieldTypeRequiredDescription
namestringyesSource name, 1 to 255 characters. Shown in the dashboard and used when the bot cites the source.
contentstringyesThe full text to index. Markdown is supported.
curl -X POST https://developers.sarufi.io/api/dev/v1/knowledge-bases/<kb-id>/sources/text \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Return Policy",
    "content": "We accept returns within 30 days of purchase. Items must be in original condition..."
  }'

Response - 201 Created with the new Source object.

Processing time

A new source is indexed in the background, usually within seconds for text. Poll Get Source until status reads COMPLETED, or FAILED with an error_message.


Add Web Source

Reads a public web page, and the pages it links to on the same site, and indexes their content.

POST /api/dev/v1/knowledge-bases/{kb_id}/sources/web
Authorization: Bearer <api-key>
Content-Type: application/json

Request Body

FieldTypeRequiredDescription
namestringyesSource name, 1 to 255 characters.
urlstringyesPublic URL to start from. Must be reachable without signing in.
curl -X POST https://developers.sarufi.io/api/dev/v1/knowledge-bases/<kb-id>/sources/web \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Help centre",
    "url": "https://yoursite.com/faq"
  }'

Response - 201 Created with the new Source object. When reading finishes, crawled_urls lists every page that was indexed.

See How web pages are read for what is kept from each page.


Get Source

GET /api/dev/v1/knowledge-bases/{kb_id}/sources/{source_id}
Authorization: Bearer <api-key>

Returns the Source object.


Update Source

Renames a source, or changes how often a web source is read again.

PATCH /api/dev/v1/knowledge-bases/{kb_id}/sources/{source_id}
Authorization: Bearer <api-key>
Content-Type: application/json
FieldTypeRequiredDescription
namestringyesSource name, 1 to 255 characters.
refresh_interval_secondsintegernoWeb sources only. How often the site is read again, at most 2592000 (30 days). 0 turns re-reading off. Leave it out to keep the rhythm Sarufi has learned from how often the site changes.
curl -X PATCH https://developers.sarufi.io/api/dev/v1/knowledge-bases/<kb-id>/sources/<source-id> \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Help centre", "refresh_interval_seconds": 86400}'

Delete Source

DELETE /api/dev/v1/knowledge-bases/{kb_id}/sources/{source_id}
Authorization: Bearer <api-key>

Response - 204 No Content


Source object

FieldTypeDescription
idstringSource ID.
knowledge_base_idstringThe KB it belongs to.
source_typestringTEXT, WEB or FILE.
statusstringIndexing state. COMPLETED when the source is searchable, FAILED when it could not be indexed.
namestringSource name.
chunk_countintegerHow many searchable passages the source produced.
error_messagestring | nullWhy indexing failed.
crawled_urlsstring[]Web sources: the pages that were indexed.
warningstringPresent when indexing finished but found little readable content, so COMPLETED does not mean the whole site is covered.
created_atstringISO 8601 timestamp.
processed_atstring | nullWhen indexing last finished.
last_crawled_atstringWeb sources: when the site was last read.
last_changed_atstringWeb sources: when its content last changed.
next_refresh_atstringWeb sources: when it is next due to be read.
refresh_interval_secondsintegerWeb sources: the current re-read interval.
crawl_failuresintegerWeb sources: consecutive failed re-reads.
refresh_abandonedbooleanWeb sources: true when the site failed too often and is no longer re-read. Fix the site, then add the source again.
{
  "id": "01KSR...",
  "knowledge_base_id": "01KAB123...",
  "source_type": "WEB",
  "status": "COMPLETED",
  "name": "Help centre",
  "chunk_count": 48,
  "error_message": null,
  "crawled_urls": ["https://yoursite.com/faq", "https://yoursite.com/shipping"],
  "created_at": "2026-10-01T09:00:00Z",
  "processed_at": "2026-10-01T09:00:41Z",
  "last_crawled_at": "2026-10-20T09:00:00Z",
  "next_refresh_at": "2026-10-21T09:00:00Z",
  "refresh_interval_seconds": 86400
}

How web pages are read

  • The main content, not the chrome. Menus, banners, cookie notices and footers are dropped. A small block marked as content, such as a side menu, never replaces the whole page.
  • FAQ and accordion pages are read in full. Answers hidden behind a collapsed question are kept, and each question and its answer is indexed as its own passage, with the page title and section, so a visitor's question finds the exact answer.
  • A page limit. A web source follows links on the same site for up to 10 pages. The limit counts pages actually read, so skipped or duplicate pages do not use it up. For a larger site, add one web source per section.
  • Kept up to date. Sites are read again on a rhythm learned from how often they change, or on refresh_interval_seconds. A re-read replaces passages only after the new ones are indexed, so search never comes back empty while a site is being refreshed.

How answers are found

Every search combines two methods and merges their rankings:

  • Keyword search finds passages that use the visitor's exact words: product codes, names, prices.
  • Meaning search finds passages that say the same thing in other words, or in another language.

When several KBs are attached, they are searched together and the KB with the highest priority wins near ties. At most two passages come from any one page, and near-duplicate passages are dropped, so the agent sees a varied set.

Each search is given a confidence:

ConfidenceMeaning
HIGHA passage clearly answers the question.
PARTIALRelated passages were found, but none answers it fully. The agent is told to answer only what the passages support.
NONENothing relevant was found. The agent says so instead of guessing.

The latest confidence is stored in the flow variable variables.rag_last_confidence, so later states can branch on it.

Routing on confidence

An LLM_AGENT action can leave for another state instead of answering from thin results, with rag_config:

{
  "type": "LLM_AGENT",
  "system_prompt": "You answer questions about our products.",
  "rag_config": {
    "low_confidence_transition": "offer_human",
    "no_results_transition": "offer_human"
  }
}
FieldDescription
low_confidence_transitionFollowed when the search is PARTIAL.
no_results_transitionFollowed when the search is NONE. Each is followed only for its own case.
low_confidence_thresholdA score from 0 to 1 (default 0.65), used only when a search returns no confidence band.

The agent's reply for that turn is still sent; the transition decides where the conversation goes next.


Chatbot ↔ KB Connections

Attach or detach a KB from a chatbot. Multiple KBs can be attached to one chatbot; they are all searched when answering.

List Attached KBs

GET /api/dev/v1/chatbots/{chatbot_id}/knowledge-bases
Authorization: Bearer <api-key>

Attach KB to Chatbot

POST /api/dev/v1/chatbots/{chatbot_id}/knowledge-bases
Authorization: Bearer <api-key>
Content-Type: application/json
FieldTypeRequiredDescription
knowledge_base_idstringyesThe KB to attach.
priorityintegerno0 or more. Higher wins near ties when several KBs match equally well.
curl -X POST https://developers.sarufi.io/api/dev/v1/chatbots/<chatbot-id>/knowledge-bases \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"knowledge_base_id": "01KAB123...", "priority": 1}'

Detach KB from Chatbot

DELETE /api/dev/v1/chatbots/{chatbot_id}/knowledge-bases/{kb_id}
Authorization: Bearer <api-key>

Response - 204 No Content. The KB itself is not deleted - only the association.

On this page