Skip to main content

Knowledge Bases

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.

GET /api/dev/v1/knowledge-bases
Authorization: Bearer <api-key>
curl -X GET https://beta-api.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://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

{
  "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://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.

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

Request Body

FieldTypeRequiredDescription
titlestringyesDocument title used in citations.
contentstringyesThe full text content to index. Markdown is supported.
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

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

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

Request Body

FieldTypeRequiredDescription
urlstringyesPublic URL to crawl. Must be accessible without authentication.
titlestringnoOverride title. If omitted, the page's <title> tag is used.
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​

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​

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
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​

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.