Skip to main content

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​

FieldDefaultWhat it changes
retrieval_modeautoauto 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.
reranktrueRe-scores the candidates with the cross-encoder. Read rerank_applied to know whether it ran.
include_contenttrueWhether content carries the chunk text. False returns the citation fields only.
expand_contextfalseFetches the chunk before and after each hit into context_window, for a wider passage to hand to a model.
graph_expansionfalseExtracts 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.
hydethe tenant's settingHypothetical 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_beforenoneUnix timestamps; keep only chunks ingested in that window.
heading_path_containsnoneCase-sensitive substring of the chunk's heading path, such as PTO Policy.
page_rangenone[start, end], inclusive page numbers.
metadata_filtersnoneEvery 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_kthe tenant's defaultCapped at 100; a larger value is refused with 422, never trimmed.
source_idsall accessibleRestrict 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 -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"}}'

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.

FieldsWhat they tell you
low_confidence, low_confidence_reasonThe 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_scaleThe 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_reasonWhether 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, hydeThree 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_filtersYour metadata_filters, echoed back even on an empty set.
derived_metadata_filters, derived_metadata_reasoning, derived_metadata_abandonedA 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_withheldCandidates 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_mstimeout 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_idCandidates 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.

The same search elsewhere

Describes the platform as of .

Was this page helpful?