Knowledge bases
Give agents documents and web pages to answer from.
A knowledge base holds the documents an agent answers from during a call: pasted text and public web pages here, plus files uploaded in the console. Attach one to an agent by setting the agent’s knowledgeBaseId (Agents).
Knowledge base object:
{ "id": "kb_…", "name": "Support", "documentCount": 2, "chunkCount": 14, "agentCount": 1 }agentCount- how many agents use it.
List knowledge bases
GET /v1/knowledge-bases · scope knowledge:read
Create a knowledge base
POST /v1/knowledge-bases · scope knowledge:write
{ "name": "Support" }Returns 201 with the knowledge base. 403 plan_feature_locked if knowledge bases are turned off for your workspace.
Get a knowledge base
GET /v1/knowledge-bases/:id · scope knowledge:read
The knowledge base plus its documents:
{ "data": { "id": "kb_…", "name": "Support", …, "documents": [ { "source": "Refunds", "type": "text", "chunkCount": 3 }, { "source": "https://example.com/shipping", "type": "link", "chunkCount": 11 } ] } }Add a text document
POST /v1/knowledge-bases/:id/documents · scope knowledge:write
| Field | Type | Required | Notes |
|---|---|---|---|
text |
string | yes | Up to 100,000 characters. |
title |
string | no | Names the document. Sending the same title again replaces that document, so this is how you update one. Without a title, each call adds a new document. |
{ "data": { "source": "Refunds", "added": 3, "replaced": 0, "chars": 1840 } }The document is searchable as soon as this returns.
Add a web page
POST /v1/knowledge-bases/:id/links · scope knowledge:write
{ "url": "https://example.com/shipping" }We fetch the page and index its text. Adding the same URL again refreshes it. If the page builds its content with JavaScript and very little text can be read, the response includes a warning; paste the text as a document instead. A page that can’t be fetched is 422.
Remove a document
DELETE /v1/knowledge-bases/:id/documents?source=…&type=… · scope knowledge:write
source and type (text, file or link) as listed on the knowledge base. Unknown document → 404.
Search
GET /v1/knowledge-bases/:id/search?q=… · scope knowledge:read
Returns the passages an agent would pull up for that question on a live call, ranked the same way. Use it to check a document answers what you expect.
{ "data": [ { "content": "Refunds are processed within 7 business days…", "score": 0.82, "source": "Refunds" } ] }Delete a knowledge base
DELETE /v1/knowledge-bases/:id · scope knowledge:write
Agents using it are detached (their knowledgeBaseId becomes null) and stop answering from it.
Next: Chat →