Knowledge bases
Your account's knowledge bases: name, kind and source of each one, and how to create, change and delete text knowledge bases.
Knowledge bases are the content your agents answer questions from: a website, a text, a file or an integration. These endpoints return their references (name, kind, source and dates), not the content, and let you create, change and delete text knowledge bases. Reading needs knowledge_bases:read; writing needs knowledge_bases:write.
| Endpoint | Route | Scope |
|---|---|---|
| List knowledge bases | GET /v1/knowledge-bases |
knowledge_bases:read |
| One knowledge base | GET /v1/knowledge-bases/{knowledge_base_id} |
knowledge_bases:read |
| Create a text knowledge base | POST /v1/knowledge-bases |
knowledge_bases:write |
| Change a text knowledge base | PATCH /v1/knowledge-bases/{knowledge_base_id} |
knowledge_bases:write |
| Delete a text knowledge base | DELETE /v1/knowledge-bases/{knowledge_base_id} |
knowledge_bases:write |
List knowledge bases
Section titled “List knowledge bases”GET /v1/knowledge-bases returns your account’s knowledge bases, paged.
| Parameter | Type | Default | Rules |
|---|---|---|---|
limit |
1 to 100 | 50 | Items per page |
cursor |
string | none | meta.next_cursor of the previous page, with the same limit |
customer_id |
UUID | the key’s customer | See what each key reads |
curl -s -H "apikey: $BOOKLINE_API_KEY" "$BASE/knowledge-bases"{ "data": [ { "id": "…", "name": "FAQ", "type": "WEBSITE", "source": "https://www.example.com/faq", "created_at": "2026-09-01T09:12:00Z", "updated_at": "2026-10-20T16:40:00Z" } ], "meta": { "limit": 50, "next_cursor": null }}| Field | What it is |
|---|---|
id |
The knowledge base’s identifier |
name |
Its name in the portal |
type |
WEBSITE, TEXT, FILE or INTEGRATION |
source |
The website or file name the content came from; null when not applicable |
created_at, updated_at |
When it was created and last updated (UTC) |
One knowledge base
Section titled “One knowledge base”GET /v1/knowledge-bases/{knowledge_base_id} returns the same fields, with an ETag header: the version to send as If-Match when you change or delete it. A knowledge base that is not your customer’s is 404 not_found.
Create a text knowledge base
Section titled “Create a text knowledge base”POST /v1/knowledge-bases creates a TEXT knowledge base from the text you send. It needs an Idempotency-Key header (see Writing data) and a key on the whole customer: a key limited to some venues gets 403 insufficient_scope. Website and file knowledge bases are created in the portal.
| Field | Rules |
|---|---|
name |
Required, 1 to 200 characters: the name the portal lists |
text |
Required, 1 to 200,000 characters of plain text: what the agents answer from |
curl -s -X POST "$BASE/knowledge-bases" \ -H "apikey: $BOOKLINE_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"name": "Opening hours", "text": "We open every day from 13:00 to 16:00 and from 20:00 to 23:30."}'The answer is 201 with the knowledge base and its ETag. Your agents use it once you link it to a venue in the portal.
Change a text knowledge base
Section titled “Change a text knowledge base”PATCH /v1/knowledge-bases/{knowledge_base_id} changes name, text or both, with the same rules. Send at least one ({} is 422 validation_failed) and the knowledge base’s ETag as If-Match.
textreplaces the whole content. There is no append: send the full text every time.- Only
TEXTknowledge bases. AWEBSITE,FILEorINTEGRATIONone is 409conflict: change it in the portal. - If a text change answers with a 5xx, send the same text again: it may not have reached your agents.
curl -s -X PATCH "$BASE/knowledge-bases/<knowledge_base_id>" \ -H "apikey: $BOOKLINE_API_KEY" \ -H "Content-Type: application/json" \ -H 'If-Match: "<etag>"' \ -d '{"text": "We open every day from 13:00 to 16:00 and from 20:00 to 00:00."}'Delete a text knowledge base
Section titled “Delete a text knowledge base”DELETE /v1/knowledge-bases/{knowledge_base_id} deletes a TEXT knowledge base and its content. Send its ETag as If-Match. The answer is 204.
- A
WEBSITE,FILEorINTEGRATIONone is 409conflict: delete it in the portal. - One a venue still uses is 409
conflict: unlink it from its venues in the portal first. Avoid linking it in the portal while you delete it: the check is made just before the delete, and a venue linked at that same moment would point at a deleted knowledge base.
Data rules
Section titled “Data rules”- References, not content. The text or the file is not returned by the API today, not even for the text knowledge bases you write.
- Venue-restricted keys. The key lists only the knowledge bases those venues use.
- If knowledge bases are created while you page, one may repeat on the next page: keep one per
id.
Related
Section titled “Related”- Writing data: versions, retries and the write limit.
- Agents: the agents that answer from them.
