Knowledge Bases | Developer API | Conversation Engine

Overview

A Knowledge Base (KB) is a collection of text sources that Conversation Engine uses to answer questions via retrieval-augmented generation (RAG). Sources can be plain text snippets or URLs that Conversation Engine 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>GET /api/dev/v1/knowledge-bases
Authorization: Bearer <api-key>

bash

curl -X GET http://localhost:3000/api/dev/v1/knowledge-bases \
  -H "Authorization: Bearer <your-api-key>"curl -X GET http://localhost:3000/api/dev/v1/knowledge-bases \
  -H "Authorization: Bearer <your-api-key>"

python

import requests
response = requests.get(
    "http://localhost:3000/api/dev/v1/knowledge-bases",
    headers={"Authorization": "Bearer <your-api-key>"},
)
print(response.json())import requests
response = requests.get(
    "http://localhost:3000/api/dev/v1/knowledge-bases",
    headers={"Authorization": "Bearer <your-api-key>"},
)
print(response.json())

javascript

const response = await fetch("http://localhost:3000/api/dev/v1/knowledge-bases", {
  headers: { "Authorization": "Bearer <your-api-key>" },
});
const data = await response.json();const response = await fetch("http://localhost:3000/api/dev/v1/knowledge-bases", {
  headers: { "Authorization": "Bearer <your-api-key>" },
});
const data = await response.json();

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
}{
  "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/jsonPOST /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 http://localhost:3000/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"
  }'curl -X POST http://localhost:3000/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"
  }'

python

import requests
response = requests.post(
    "http://localhost:3000/api/dev/v1/knowledge-bases",
    headers={"Authorization": "Bearer <your-api-key>"},
    json={"name": "Product FAQ", "description": "Common product and pricing questions"},
)
print(response.json())import requests
response = requests.post(
    "http://localhost:3000/api/dev/v1/knowledge-bases",
    headers={"Authorization": "Bearer <your-api-key>"},
    json={"name": "Product FAQ", "description": "Common product and pricing questions"},
)
print(response.json())

javascript

const response = await fetch("http://localhost:3000/api/dev/v1/knowledge-bases", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Product FAQ",
    description: "Common product and pricing questions",
  }),
});
const data = await response.json();const response = await fetch("http://localhost:3000/api/dev/v1/knowledge-bases", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Product FAQ",
    description: "Common product and pricing questions",
  }),
});
const data = await response.json();

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"
}{
  "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>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>GET /api/dev/v1/knowledge-bases/{kb_id}/sources
Authorization: Bearer <api-key>

bash

curl -X GET http://localhost:3000/api/dev/v1/knowledge-bases/<kb-id>/sources \
  -H "Authorization: Bearer <your-api-key>"curl -X GET http://localhost:3000/api/dev/v1/knowledge-bases/<kb-id>/sources \
  -H "Authorization: Bearer <your-api-key>"

python

import requests
response = requests.get(
    "http://localhost:3000/api/dev/v1/knowledge-bases/<kb-id>/sources",
    headers={"Authorization": "Bearer <your-api-key>"},
)
print(response.json())import requests
response = requests.get(
    "http://localhost:3000/api/dev/v1/knowledge-bases/<kb-id>/sources",
    headers={"Authorization": "Bearer <your-api-key>"},
)
print(response.json())

javascript

const response = await fetch("http://localhost:3000/api/dev/v1/knowledge-bases/<kb-id>/sources", {
  headers: { "Authorization": "Bearer <your-api-key>" },
});
const data = await response.json();const response = await fetch("http://localhost:3000/api/dev/v1/knowledge-bases/<kb-id>/sources", {
  headers: { "Authorization": "Bearer <your-api-key>" },
});
const data = await response.json();

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/jsonPOST /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 http://localhost:3000/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..."
  }'curl -X POST http://localhost:3000/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..."
  }'

python

import requests
response = requests.post(
    "http://localhost:3000/api/dev/v1/knowledge-bases/<kb-id>/sources/text",
    headers={"Authorization": "Bearer <your-api-key>"},
    json={
        "title": "Return Policy",
        "content": "We accept returns within 30 days of purchase. Items must be in original condition...",
    },
)
print(response.json())import requests
response = requests.post(
    "http://localhost:3000/api/dev/v1/knowledge-bases/<kb-id>/sources/text",
    headers={"Authorization": "Bearer <your-api-key>"},
    json={
        "title": "Return Policy",
        "content": "We accept returns within 30 days of purchase. Items must be in original condition...",
    },
)
print(response.json())

javascript

const response = await fetch("http://localhost:3000/api/dev/v1/knowledge-bases/<kb-id>/sources/text", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Return Policy",
    content: "We accept returns within 30 days of purchase. Items must be in original condition...",
  }),
});
const data = await response.json();const response = await fetch("http://localhost:3000/api/dev/v1/knowledge-bases/<kb-id>/sources/text", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Return Policy",
    content: "We accept returns within 30 days of purchase. Items must be in original condition...",
  }),
});
const data = await response.json();

Response - 201 Created

json

{
  "id": "01KSR...",
  "kb_id": "01KAB123...",
  "type": "text",
  "title": "Return Policy",
  "status": "processing",
  "created_at": "2026-02-10T11:00:00Z"
}{
  "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/jsonPOST /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 http://localhost:3000/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"
  }'curl -X POST http://localhost:3000/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"
  }'

python

import requests
response = requests.post(
    "http://localhost:3000/api/dev/v1/knowledge-bases/<kb-id>/sources/web",
    headers={"Authorization": "Bearer <your-api-key>"},
    json={"url": "https://yoursite.com/faq", "title": "FAQ Page"},
)
print(response.json())import requests
response = requests.post(
    "http://localhost:3000/api/dev/v1/knowledge-bases/<kb-id>/sources/web",
    headers={"Authorization": "Bearer <your-api-key>"},
    json={"url": "https://yoursite.com/faq", "title": "FAQ Page"},
)
print(response.json())

javascript

const response = await fetch("http://localhost:3000/api/dev/v1/knowledge-bases/<kb-id>/sources/web", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://yoursite.com/faq", title: "FAQ Page" }),
});
const data = await response.json();const response = await fetch("http://localhost:3000/api/dev/v1/knowledge-bases/<kb-id>/sources/web", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://yoursite.com/faq", title: "FAQ Page" }),
});
const data = await response.json();

Delete Source

http

DELETE /api/dev/v1/knowledge-bases/{kb_id}/sources/{source_id}
Authorization: Bearer <api-key>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>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/jsonPOST /api/dev/v1/chatbots/{chatbot_id}/knowledge-bases
Authorization: Bearer <api-key>
Content-Type: application/json

bash

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

python

import requests
response = requests.post(
    "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/knowledge-bases",
    headers={"Authorization": "Bearer <your-api-key>"},
    json={"kb_id": "01KAB123..."},
)
print(response.json())import requests
response = requests.post(
    "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/knowledge-bases",
    headers={"Authorization": "Bearer <your-api-key>"},
    json={"kb_id": "01KAB123..."},
)
print(response.json())

javascript

const response = await fetch("http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/knowledge-bases", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ kb_id: "01KAB123..." }),
});
const data = await response.json();const response = await fetch("http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/knowledge-bases", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ kb_id: "01KAB123..." }),
});
const data = await response.json();

Detach KB from Chatbot

http

DELETE /api/dev/v1/chatbots/{chatbot_id}/knowledge-bases/{kb_id}
Authorization: Bearer <api-key>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.