Search retrieval options
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 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
- Python
- TypeScript
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"}}'
import requests
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"])
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
hybridon a deployment with no sparse vectors runs dense retrieval and reports the degradation in theretrievalreceipt; a comparison never turns into an error. - Short queries are routed to the fast path when query routing is on, so
rerank: truedoes not guarantee a rerank. Readrerank_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
resultswithempty_reasonset totimeout: readtimed_out_stage; expansion and graph options add stages, so drop them or ask an administrator about the search budget. low_confidence_reasonissubject_absent: the knowledge base probably does not cover the topic; do not present the hits as an answer.rerank_appliedis false withcall_failed: the reranking tier has no healthy model; an administrator sees it on the AI Gateway's Tiers tab.- 401 with
AUTH_ERRORalthough the key works for chat: the key lacks the Knowledge search scope, which the gateway checks while validating the key.
The same search elsewhere