# Search retrieval options

Every switch on the search route, what each one changes in retrieval, and how to read the receipt the response carries about what the pipeline actually did.

`POST /public/v1/search` needs one field, `query`. Eleven optional fields change how retrieval runs, and the response carries a receipt of what the pipeline actually did. [Search with citations](/developers/guides/search-with-citations) covers the basic call and how to quote a hit; this page is the reference for tuning it.

**Who can use it:** anyone holding an API key with the **Knowledge search** scope. Results are filtered by the permissions of the key's owner, so two keys can get different results for one query.

## The options

| Field | Default | What it changes |
| --- | --- | --- |
| `retrieval_mode` | `auto` | `auto` lets the retriever decide: hybrid when the embedding model returned a sparse vector, dense-only otherwise. `hybrid` and `dense` pin the choice, which is what makes an A/B of the two arms possible. Hybrid on a deployment without sparse vectors degrades to dense and the receipt says so; it never fails. |
| `rerank` | `true` | Re-scores the candidates with the cross-encoder. Read `rerank_applied` to know whether it ran. |
| `include_content` | `true` | Whether `content` carries the chunk text. False returns the citation fields only. |
| `expand_context` | `false` | Fetches the chunk before and after each hit into `context_window`, for a wider passage to hand to a model. |
| `graph_expansion` | `false` | Extracts entities from the query, walks the knowledge graph, and boosts or injects chunks linked to related entities. Such hits carry `retrieval_source` of `graph` or `graph_boost` and an `entity_path`. |
| `hyde` | the tenant's setting | Hypothetical Document Embedding: a model writes a passage that would answer the query and that passage is embedded instead of the question. Unset follows the tenant's setting; `true` or `false` overrides it for this request, within the deployment's kill switch. Costs about 200 ms for the model call, cached after first use. |
| `created_after`, `created_before` | none | Unix timestamps; keep only chunks ingested in that window. |
| `heading_path_contains` | none | Case-sensitive substring of the chunk's heading path, such as `PTO Policy`. |
| `page_range` | none | `[start, end]`, inclusive page numbers. |
| `metadata_filters` | none | Every key and value must match, values compared as text. Each key must be declared filterable on a source in scope, or the search fails with 422 naming the key; an undeclared key is never silently dropped. |
| `top_k` | the tenant's default | Capped at 100; a larger value is refused with 422, never trimmed. |
| `source_ids` | all accessible | Restrict to these sources. |

## Quick start

A pinned hybrid search, reranked, limited to one department's documents and the leave policy's headings, with neighbouring chunks:

**cURL**

```bash
curl -X POST "https://<your tenant host>/public/v1/search" \
  -H "Authorization: Bearer kapi_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "How many days of carer leave can I take?",
       "retrieval_mode": "hybrid", "rerank": true, "top_k": 5, "expand_context": true,
       "heading_path_contains": "Leave", "metadata_filters": {"department": "HR"}}'
```

**Python**

```python

BASE = "https://<your tenant host>/public/v1"
HEADERS = {"Authorization": "Bearer kapi_..."}

body = requests.post(f"{BASE}/search", headers=HEADERS, json={
    "query": "How many days of carer leave can I take?",
    "retrieval_mode": "hybrid", "rerank": True, "top_k": 5, "expand_context": True,
    "heading_path_contains": "Leave", "metadata_filters": {"department": "HR"},
}).json()

if body["low_confidence"]:
    print("low confidence:", body["low_confidence_reason"], body["best_score"], body["best_score_scale"])
if not body["rerank_applied"]:
    print("not reranked:", body["rerank_reason"])
for hit in body["results"]:
    print(hit["score"], hit["retrieval_source"], hit["source_label"])
```

**TypeScript**

```typescript
const BASE = "https://<your tenant host>/public/v1";
const headers = { Authorization: "Bearer kapi_...", "Content-Type": "application/json" };

const r = await fetch(`${BASE}/search`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    query: "How many days of carer leave can I take?",
    retrieval_mode: "hybrid", rerank: true, top_k: 5, expand_context: true,
    heading_path_contains: "Leave", metadata_filters: { department: "HR" },
  }),
});
const body = await r.json();
if (body.low_confidence) console.warn("low confidence:", body.low_confidence_reason);
if (!body.rerank_applied) console.warn("not reranked:", body.rerank_reason);
for (const hit of body.results) console.log(hit.score, hit.retrieval_source, hit.source_label);
```

## Read the receipt

The result list is only part of the answer. These fields say how it was produced, and they are present on empty responses too, which is the point: "nothing matched" and "the search timed out" are different answers.

| Fields | What they tell you |
| --- | --- |
| `low_confidence`, `low_confidence_reason` | The set is a best-effort fallback. The reason is `below_gate` (no candidate cleared the threshold), `subject_absent` (the query names a subject none of the results contain, so the answer is probably not in this knowledge base), `below_floor` (the best result cleared the gate but sits under the floor), `flat_margin` (the top result does not stand out) or `uncalibrated` (hybrid fusion scores with the reranker unavailable). |
| `best_score`, `threshold_applied`, `best_score_scale` | The numbers behind the verdict and their scale: `cosine` for dense similarity, `cross_encoder` for the reranker's relevance score, `fusion` for hybrid scores without a rerank, which have no calibrated cutoff. |
| `rerank_applied`, `rerank_reason` | Whether the cross-encoder re-scored the set. When it did not: `not_requested`, `routed_fast_path` (the complexity router skipped it, which with routing enabled is every query of five words or fewer), `call_failed` (the reranking tier has no model, or the call errored), `no_candidates` or `rerank_disabled` (an administrator turned reranking off). Each has a different fix. |
| `retrieval`, `routing`, `hyde` | Three receipts: the resolved retrieval mode and any degradation; the complexity-routing decision, including whether the graph was consulted; and what HyDE did, including a timeout that fell back to the raw query. |
| `applied_metadata_filters` | Your `metadata_filters`, echoed back even on an empty set. |
| `derived_metadata_filters`, `derived_metadata_reasoning`, `derived_metadata_abandoned` | A filter the platform derived from the question itself, kept apart from yours. Exactly one of `derived_metadata_filters` and `derived_metadata_abandoned` is set: the platform either narrowed, or tried to and gave up because nothing was left. |
| `results_withheld` | Candidates dropped because the key's owner may not read them. Distinguishes "no more matches" from "hidden by permissions". |
| `empty_reason`, `timed_out_stage`, `stage_timings_ms` | `timeout` when the tenant's search budget ran out, the stage that was cut short, and the milliseconds each stage took in order. A stage that did not run is absent. |
| `total_candidates`, `search_time_ms`, `warnings`, `event_id` | Candidates before reranking and filtering, wall-clock time, stale-source and permission warnings, and an id to pass back with feedback. |

Each hit carries `chunk_id`, `content`, `score`, `vector_score` (the score before reranking), `heading_path`, `page_number`, `chunk_index`, `retrieval_source`, `context_window` when you asked for it, `entity_path` on graph hits, a `source` object with the document and source identifiers, and `source_label`, the one string to quote.

## Limits and behaviour

- Pinning `hybrid` on a deployment with no sparse vectors runs dense retrieval and reports the degradation in the `retrieval` receipt; a comparison never turns into an error.
- Short queries are routed to the fast path when query routing is on, so `rerank: true` does not guarantee a rerank. Read `rerank_applied`.
- The confidence fields describe the whole set, not one hit; a set can be low confidence while its top hit is correct.

## Troubleshooting

- **422 naming a metadata key**: the key is not declared filterable on any source in scope.
- **Empty `results` with `empty_reason` set to `timeout`**: read `timed_out_stage`; expansion and graph options add stages, so drop them or ask an administrator about the search budget.
- **`low_confidence_reason` is `subject_absent`**: the knowledge base probably does not cover the topic; do not present the hits as an answer.
- **`rerank_applied` is false with `call_failed`**: the reranking tier has no healthy model; an administrator sees it on the AI Gateway's Tiers tab.
- **401 with `AUTH_ERROR` although the key works for chat**: the key lacks the Knowledge search scope, which the gateway checks while validating the key.

## Related

- [Search with citations](/developers/guides/search-with-citations)
- [Sources, sync and the source-synced webhook](/developers/guides/sources-and-sync)
- Knowledge

Source: https://docs.katonic.ai/developers/guides/search-options
