> ## Documentation Index
> Fetch the complete documentation index at: https://docs.powabase.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Context Handlers

> Execute standalone knowledge retrieval outside of agent runs. Useful for building custom RAG pipelines.

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.

<CodeGroup>
  ```python Python theme={null}
  response = requests.get(f"{BASE_URL}/api/context-handlers", headers=headers)
  ```

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

  ```bash cURL theme={null}
  curl '{BASE_URL}/api/context-handlers' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"
  ```
</CodeGroup>

### POST /api/context-handlers

Create and execute a context handler. Retrieves relevant chunks from one or more knowledge bases.

<RequestExample>
  ```json Request theme={null}
  {
    "query": "How to get started?",
    "knowledge_bases": [
      { "id": "kb-uuid", "top_k": 5 }
    ],
    "max_context_tokens": 8000
  }
  ```
</RequestExample>

<CodeGroup>
  ```python Python theme={null}
  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,
  })
  ```

  ```typescript TypeScript theme={null}
  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,
    }),
  });
  ```

  ```bash cURL theme={null}
  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}]}'
  ```
</CodeGroup>

<Note>
  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).
</Note>

### GET /api/context-handlers/{id}

Get a context handler result by ID.

<ParamField path="id" type="string" required>
  Handler ID
</ParamField>

<CodeGroup>
  ```python Python theme={null}
  response = requests.get(f"{BASE_URL}/api/context-handlers/{handler_id}", headers=headers)
  ```

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

  ```bash cURL theme={null}
  curl '{BASE_URL}/api/context-handlers/{id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"
  ```
</CodeGroup>

## 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     |