Navigation
Resources HubUser Documentation

Resources

Knowledge Bases

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

Overview

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 URLs that Sarufi will crawl.

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 queried for a relevant answer.

List Knowledge Bases

Returns all KBs in the workspace.

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

Response — 200 OK

json
{
  "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

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

Body

namestringrequired

Display name for the knowledge base.

descriptionstringoptional

Optional description of what this KB contains.

bash
curl -X POST https://beta-api.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

json
{
  "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

http
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

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

Add Text Source

Indexes a plain text document directly.

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

Body

titlestringrequired

Document title used in citations.

contentstringrequired

The full text content to index. Markdown is supported.

bash
curl -X POST https://beta-api.sarufi.io/api/dev/v1/knowledge-bases/<kb-id>/sources/text \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Return Policy",
    "content": "We accept returns within 30 days of purchase. Items must be in original condition..."
  }'

Response — 201 Created

json
{
  "id": "01KSR...",
  "kb_id": "01KAB123...",
  "type": "text",
  "title": "Return Policy",
  "status": "processing",
  "created_at": "2026-02-10T11:00:00Z"
}

Processing time

After adding a source its status is processing. Indexing usually completes within a few seconds. Poll the list sources endpoint or check status until it reads ready.

Add Web Source

Crawls a URL and indexes its content.

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

Body

urlstringrequired

Public URL to crawl. Must be accessible without authentication.

titlestringoptional

Override title. If omitted, the page's <title> tag is used.

bash
curl -X POST https://beta-api.sarufi.io/api/dev/v1/knowledge-bases/<kb-id>/sources/web \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yoursite.com/faq",
    "title": "FAQ Page"
  }'

Delete Source

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

Response — 204 No Content

Chatbot ↔ KB Connections

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

List Attached KBs

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

Attach KB to Chatbot

http
POST /api/dev/v1/chatbots/{chatbot_id}/knowledge-bases
Authorization: Bearer <api-key>
Content-Type: application/json
bash
curl -X POST https://beta-api.sarufi.io/api/dev/v1/chatbots/<chatbot-id>/knowledge-bases \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"kb_id": "01KAB123..."}'

Detach KB from Chatbot

http
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.

PreviousIntegrationsNextAnalytics