Skip to content

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

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
Ventana de terminal
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)

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.

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
Ventana de terminal
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.

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.

  • text replaces the whole content. There is no append: send the full text every time.
  • Only TEXT knowledge bases. A WEBSITE, FILE or INTEGRATION one is 409 conflict: 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.
Ventana de terminal
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 /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, FILE or INTEGRATION one is 409 conflict: 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.
  • 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.
  • Writing data: versions, retries and the write limit.
  • Agents: the agents that answer from them.