Knowledge base API

Everything under /api/knowledge-bases requires a platform JWT and is scoped to your tenant. Retrieval itself is not here: an agent reaches a knowledge base through a RAG tool, covered in Retrieval.

Setup

POST /api/knowledge-bases/initialize    Create the knowledge schema and its tables
GET  /api/knowledge-bases/status        Whether this tenant's index is set up

initialize is safe to repeat. It creates what is missing and never drops or resets a table, so running it to recover from a half-finished setup cannot cost you an index.

Knowledge bases

GET    /api/knowledge-bases          List this tenant's knowledge bases
POST   /api/knowledge-bases          Create one, optionally with files in the same request
GET    /api/knowledge-bases/{id}     One, with its document list
PUT    /api/knowledge-bases/{id}     Update name, description, alias, tags, configuration
DELETE /api/knowledge-bases/{id}     Delete it, its chunks and its stored files

POST accepts multipart/form-data, so a knowledge base can be created and populated in one call, or created empty with JSON and filled later.

Documents

POST   /api/knowledge-bases/{id}/upload                        Add files to an existing base
GET    /api/knowledge-bases/{id}/documents/{documentId}        Document metadata
GET    /api/knowledge-bases/{id}/documents/{documentId}/download  The original file
DELETE /api/knowledge-bases/{id}/documents/{documentId}        Remove it from this base

curl -X POST https://service.ensembleapp.dev/api/knowledge-bases/{id}/upload \
  -H 'Authorization: Bearer <jwt>' \
  -F 'files=@handbook.pdf' \
  -F 'files=@refund-policy.md'

Uploading returns once the files are stored. Indexing happens afterwards, so poll the document's status, or read the knowledge base and look at its documents array. See Documents for what each status means.

Removing a document deletes the chunks for that document in that knowledge base. A document indexed into several bases keeps the others, and the file is removed from storage only once nothing refers to it.

Maintenance

GET  /api/knowledge-bases/{id}/health    Compare expected counts against what is indexed
POST /api/knowledge-bases/{id}/reindex   Rebuild every document's chunks from storage

health is the endpoint to reach for when retrieval returns less than you expect. It reports the document and chunk counts the platform believes it has against what is actually in the index, whether every chunk has an embedding, whether the vector extension is present, and a list of recommendations naming anything wrong.

reindex re-processes the stored uploads with the knowledge base's current settings. It takes an advisory lock, so a second rebuild of the same base while one is running answers 409 rather than queueing. Both of these require edit permission on the knowledge base.

Testing retrieval

POST /api/knowledge-bases/{id}/test

curl -X POST https://service.ensembleapp.dev/api/knowledge-bases/{id}/test \
  -H 'Authorization: Bearer <jwt>' \
  -H 'Content-Type: application/json' \
  -d '{ "query": "What is our refund window?", "topK": 15, "model": "gpt-4o-mini" }'

The response carries both the passages, with their similarity scores and metadata, and the answer composed from them. Read the passages first: the answer only tells you what a model could make of what retrieval found, and a fluent answer over poor passages is the failure mode this endpoint exists to expose.