Skip to main content
Context handlers provide standalone RAG retrieval without requiring an agent. Send a query with one or more knowledge base configurations, and the handler retrieves the most relevant chunks from each knowledge base. This is useful when you want to implement your own LLM integration but still leverage the platform’s vector search.

​
Common Patterns

Execute a context handler with POST /api/context-handlers, providing a query and an array of knowledge_bases (each specifying a knowledge_base_id and optional top_k). The response includes the retrieved chunks ranked by relevance, which you can inject into your own LLM prompts.

​
GET /api/context-handlers

List context handlers with pagination. 
response = requests.get(f"{BASE_URL}/api/context-handlers", headers=headers)

​
POST /api/context-handlers

Create and execute a context handler — retrieves relevant chunks from one or more knowledge bases. 
{
  "query": "How to get started?",
  "knowledge_bases": [
    { "id": "kb-uuid", "top_k": 5 }
  ],
  "max_context_tokens": 8000
}

response = requests.post(f"{BASE_URL}/api/context-handlers", headers=headers, json={
    "query": "How to get started?",
    "knowledge_bases": [{"id": kb_id, "top_k": 5}],
    "max_context_tokens": 8000,
})
Request body uses knowledge_bases; the response payload carries it back as knowledge_base_configs. The response also includes a metadata object (with query_enrichment: the rewritten / expanded queries the platform actually issued) and errors (per-KB partial failures, if any).

​
GET /api/context-handlers/

Get a context handler result by ID.
​
id
string
required
Handler ID
response = requests.get(f"{BASE_URL}/api/context-handlers/{handler_id}", headers=headers)

​
Error Responses

Context-handler routes return {"error": "<message>"}.
StatusDescription
400query is required (POST), or knowledge_bases is required and must be non-empty (POST)
404No context handler exists with the given ID
500Retrieval failed during handler creation — body contains the underlying error message