Knowledge bases
These endpoints need a Keycloak access token. See Authentication. For how knowledge bases work, see Knowledge bases.
Create a knowledge base
/knowledge-basesNeeds the developer or admin role on the project.
Body
project_idstringrequirednamestringrequiredembedding_modelstringrequiredall-minilm-embed. The knowledge base stores the model's reference and uses it for its whole life.Response fields
idstringoptionalkb-1a2b3c4d5e6f.embedding_modelstringoptionalResponses
List knowledge bases
/knowledge-basesNeeds any role on the project.
Query parameters
project_idstringrequiredEach entry has id, project_id, name, embedding_model, created_at and created_by.
Upload a document
/knowledge-bases/{kb_id}/documentsUploads 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.txt or .md file, in UTF-8.Responses
id, filename and status..txt or .md.List documents
/knowledge-bases/{kb_id}/documentsEvery 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
/documents/{document_id}/statusLive progress of one document's ingestion. When it finishes, the document's record is updated. Needs any role on the project.
Response fields
stagestringoptionalfetching, chunking, embedding, upserting, ready or failed.chunk_countinteger or nulloptionaldetailstring or nulloptionalRetry a failed document
/documents/{document_id}/retryIngests a failed document again from the stored file. Needs the developer or admin role on the project.
Responses
pending again.Search a knowledge base
/knowledge-bases/{kb_id}/searchReturns 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
querystringrequiredtop_kintegeroptionalscore_thresholdnumberoptionalResponse fields
results[].textstringoptionalresults[].scorenumberoptionalresults[].filenamestringoptionalresults[].document_idstringoptionalresults[].chunk_indexintegeroptionalretrievedintegeroptionalfiltered_outintegeroptionalreasonstringoptionalnot_ingested (no document has finished) or embedding_unavailable (the embedding model is not being served). detail explains.