Knowledge Hub Retrieve APIs - retrieval
UpdatedDownload OpenAPI Specification: Download
For more information about Postman collections, forking, and making your first API call, refer to the Working with Boomi APIs on Postman page.
Retrieve chunks
Retrieve knowledge chunks matching the query.
Searches the Knowledge Base's indexed chunks and returns the top matches with
relevance scores. The retrieval_mode selects semantic (vector), lexical
(BM25 keyword), or hybrid search; filters narrows results by indexed
metadata fields; retrieval_config_override tweaks scoring per request.
Requires a valid Boomi platform JWT (Bearer token) holding the
KNOWLEDGE_HUB_KB_RETRIEVE privilege; a token without it gets a 403. The
token's account claim identifies the caller's Boomi tenant and scopes
the search to that tenant's Knowledge Bases; a Knowledge Base outside it is
a 404.
Required privileges: KNOWLEDGE_HUB_KB_RETRIEVE.
Authorizations:
path Parameters
| knowledge_base_id required | string <uuid> (Knowledge Base Id) UUID of the Knowledge Base to search |
Request Body schema: application/jsonrequired
| query required | string (Query) [ 1 .. 10000 ] characters |
Top K (integer) or Top K (null) (Top K) | |
RetrievalMode (string) or null | |
Filters (object) or Filters (null) (Filters) | |
RetrievalConfigOverride (object) or null |
Responses
Response Schema: application/json
required | Array of objects (Chunks) |
required | object (SettingsUsed) Effective settings used for the retrieval operation. |
Activity Id (string) or Activity Id (null) (Activity Id) |
Request samples
- Payload
{- "filters": {
- "department": "HR"
}, - "query": "What is the parental leave policy?",
- "retrieval_mode": "hybrid",
- "top_k": 5
}Response samples
- 200
- 400
- 401
- 403
- 404
- 409
- 422
- 503
{- "activity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "chunks": [
- {
- "chunk_id": "c3d9a1f0-1a2b-4c3d-8e5f-6a7b8c9d0e1f",
- "content": "Employees are eligible for parental leave after six months of employment.",
- "metadata": {
- "chunk_index": 0,
- "ds_id": "b7a1e0f2-...",
- "record_id": "doc-42",
- "total_chunks": 3
}, - "score": 0.91,
- "source_reference": {
- "type": "file",
- "uri": "s3://kh-ingest/hr-policies/leave.pdf"
}
}
], - "settings_used": {
- "embedding_model": "cohere.embed-v4:0",
- "retrieval_config": {
- "fields": {
- "content": {
- "boost": 1.5
}
}
}, - "retrieval_mode": "hybrid",
- "top_k": 5
}
}