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/jsonRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Display name for the knowledge base. |
description | string | no | Optional 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/jsonRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Source name, 1 to 255 characters. Shown in the dashboard and used when the bot cites the source. |
content | string | yes | The 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/jsonRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Source name, 1 to 255 characters. |
url | string | yes | Public 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| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Source name, 1 to 255 characters. |
refresh_interval_seconds | integer | no | Web 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
| Field | Type | Description |
|---|---|---|
id | string | Source ID. |
knowledge_base_id | string | The KB it belongs to. |
source_type | string | TEXT, WEB or FILE. |
status | string | Indexing state. COMPLETED when the source is searchable, FAILED when it could not be indexed. |
name | string | Source name. |
chunk_count | integer | How many searchable passages the source produced. |
error_message | string | null | Why indexing failed. |
crawled_urls | string[] | Web sources: the pages that were indexed. |
warning | string | Present when indexing finished but found little readable content, so COMPLETED does not mean the whole site is covered. |
created_at | string | ISO 8601 timestamp. |
processed_at | string | null | When indexing last finished. |
last_crawled_at | string | Web sources: when the site was last read. |
last_changed_at | string | Web sources: when its content last changed. |
next_refresh_at | string | Web sources: when it is next due to be read. |
refresh_interval_seconds | integer | Web sources: the current re-read interval. |
crawl_failures | integer | Web sources: consecutive failed re-reads. |
refresh_abandoned | boolean | Web 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:
| Confidence | Meaning |
|---|---|
HIGH | A passage clearly answers the question. |
PARTIAL | Related passages were found, but none answers it fully. The agent is told to answer only what the passages support. |
NONE | Nothing 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"
}
}| Field | Description |
|---|---|
low_confidence_transition | Followed when the search is PARTIAL. |
no_results_transition | Followed when the search is NONE. Each is followed only for its own case. |
low_confidence_threshold | A 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| Field | Type | Required | Description |
|---|---|---|---|
knowledge_base_id | string | yes | The KB to attach. |
priority | integer | no | 0 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.