Skip to main content

Knowledge bases

These endpoints need a Keycloak access token. See Authentication. For how knowledge bases work, see Knowledge bases.

Create a knowledge base​

POST/knowledge-bases

Needs the developer or admin role on the project.

Body​

project_idstringrequired
The project.
namestringrequired
The knowledge base's name.
embedding_modelstringrequired
The catalog id of a built embedding model, such as all-minilm-embed. The knowledge base stores the model's reference and uses it for its whole life.

Response fields​

idstringoptional
The knowledge base id, such as kb-1a2b3c4d5e6f.
embedding_modelstringoptional
The model reference it embeds with.

Responses​

200
Created.
400
No embedding model with this catalog id.
409
The embedding model is not built yet.

List knowledge bases​

GET/knowledge-bases

Needs any role on the project.

Query parameters​

project_idstringrequired
The project.

Each entry has id, project_id, name, embedding_model, created_at and created_by.

Upload a document​

POST/knowledge-bases/{kb_id}/documents

Uploads one file as multipart/form-data and starts ingesting it. Returns at once with status pending. Needs the developer or admin role on the project.

Form fields​

filefilerequired
A .txt or .md file, in UTF-8.

Responses​

200
Uploaded. Returns the document's id, filename and status.
400
The file is not .txt or .md.
404
No such knowledge base.

List documents​

GET/knowledge-bases/{kb_id}/documents

Every document in a knowledge base, with id, filename, status (pending, ready or failed), chunk_count, error_detail and created_at. Needs the developer or admin role on the project.

A document's status here is brought up to date when its ingestion status is read. Poll that endpoint after an upload.

Get ingestion status​

GET/documents/{document_id}/status

Live progress of one document's ingestion. When it finishes, the document's record is updated. Needs any role on the project.

Response fields​

stagestringoptional
fetching, chunking, embedding, upserting, ready or failed.
chunk_countinteger or nulloptional
How many chunks were stored.
detailstring or nulloptional
Why it failed.

Retry a failed document​

POST/documents/{document_id}/retry

Ingests a failed document again from the stored file. Needs the developer or admin role on the project.

Responses​

200
Restarted. The document is pending again.
404
No such document.
409
The document has not failed, or an ingestion of it is already running.

Search a knowledge base​

POST/knowledge-bases/{kb_id}/search

Returns the chunks closest in meaning to a query. This is what an agent's search_knowledge_base tool gets. Needs the developer or admin role on the project.

Body​

querystringrequired
The question, up to 2,000 characters.
top_kintegeroptional
How many chunks to fetch, from 1 to 20. Default 5.
score_thresholdnumberoptional
Drop chunks scoring below this, from 0 to 1. Default 0.28.

Response fields​

results[].textstringoptional
The chunk.
results[].scorenumberoptional
How close it is to the query. Higher is closer.
results[].filenamestringoptional
The document it came from.
results[].document_idstringoptional
That document's id.
results[].chunk_indexintegeroptional
The chunk's position in the document.
retrievedintegeroptional
How many chunks were fetched before the threshold.
filtered_outintegeroptional
How many the threshold dropped.
reasonstringoptional
Only when nothing could be searched: not_ingested (no document has finished) or embedding_unavailable (the embedding model is not being served). detail explains.

Responses​

200
The results.
404
No such knowledge base.
502
The search service failed or rejected the API's credential.
Was this page helpful?