Context Handlers - Powabase

Context handlers run standalone RAG retrieval without an agent. Send a query with one or more knowledge base configurations, and the handler retrieves the most relevant chunks from each knowledge base. Use this when you want your own LLM integration but still want 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)

const res = await fetch(`${BASE_URL}/api/context-handlers`, { headers });

curl '{BASE_URL}/api/context-handlers' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

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,
})

const res = await fetch(`${BASE_URL}/api/context-handlers`, {
  method: "POST", headers,
  body: JSON.stringify({
    query: "How to get started?",
    knowledge_bases: [{ id: kbId, top_k: 5 }],
    max_context_tokens: 8000,
  }),
});

curl -X POST '{BASE_URL}/api/context-handlers' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"query": "How to get started?", "knowledge_bases": [{"id": "kb-uuid", "top_k": 5}]}'

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 or 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.

string

required

Handler ID

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

const res = await fetch(`${BASE_URL}/api/context-handlers/${handlerId}`, { headers });

curl '{BASE_URL}/api/context-handlers/{id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

Error Responses

Context-handler routes return {"error": "<message>"}.

Status	Description
400	`query` is required (POST), or `knowledge_bases` is required and must be non-empty (POST)
404	No context handler exists with the given ID
500	Retrieval failed during handler creation — body contains the underlying error message

​Common Patterns

​GET /api/context-handlers

​POST /api/context-handlers

​GET /api/context-handlers/

​Error Responses

Common Patterns

GET /api/context-handlers

POST /api/context-handlers

GET /api/context-handlers/

Error Responses