Search with citations
The search route returns ranked passages from the knowledge sources the key's owner may read. Every hit names the document it came from, and the gateway adds a source_label, one quotable string, so your application can cite exactly what was read.
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 the same query.
Recorded on .
- Create a key for search
On the Developer Hub's API keys tab, select Create Key and keep only the Knowledge search scope. Copy the key; it is shown once.
- List the sources and search
GET /public/v1/sourceslists the sources the key can search, with their sync status and document counts. SendPOST /public/v1/searchwith aqueryfrom your application for the ranked passages. - Cite each passage
Quote each hit's
source_labeland link itsdocument_url. The same question on Search & Test in Knowledge Management shows the same documents.
Prerequisites
- An API key with the Knowledge search scope. See Authentication.
- Knowledge sources that have synced.
GET /public/v1/sourceslists them with their sync status and document counts, if you want to search a subset by id.
Search and cite
-
Ask the question.
queryis the only required field.top_kcaps the number of passages at 100, andrerankre-scores the candidates with the cross-encoder.curl -X POST "https://<your tenant host>/public/v1/search" \-H "Authorization: Bearer kapi_..." \-H "Content-Type: application/json" \-d '{"query": "What is the notice period for resignations?", "top_k": 5, "rerank": true}' -
Read each hit. Every entry of
resultscarries the passage (content), itsscore, where it sits in the document (heading_path,page_number,chunk_index), how it was found (retrieval_source: vector, graph or graph_boost) and asourceobject withdocument_title,document_url,source_file_url,source_nameandconnector_type.source_labelis the first of the document title, the source name, the document URL and the file URL that has a value.import requestsr = requests.post("https://<your tenant host>/public/v1/search",headers={"Authorization": "Bearer kapi_..."},json={"query": "What is the notice period for resignations?", "top_k": 5})body = r.json()for hit in body["results"]:link = hit["source"].get("document_url") or hit["source"].get("source_file_url")print(f"[{hit['source_label']}] {hit['content'][:160]} {link or ''}") -
Judge the result set before you show it.
low_confidenceis true when no result cleared the confidence threshold;low_confidence_reasonsays why (below_gate,subject_absentorbelow_floor), andbest_score,threshold_appliedandbest_score_scalegive the numbers.results_withheldcounts passages dropped because the caller may not read them. An empty list withempty_reasonset totimeoutmeans the search budget ran out attimed_out_stage, not that nothing matched. -
Narrow or widen the search.
source_idslimits the search to named sources;heading_path_contains,page_range,created_afterandcreated_beforefilter passages;metadata_filtersmatches document metadata, but each key must be declared filterable on a source in scope or the call fails with 422 naming the key.expand_contextadds the neighbouring passages ascontext_window,graph_expansionbrings in passages linked through the knowledge graph, andhydeembeds a hypothetical answer instead of the question.
Show the citation
Quote source_label as the citation and link it to document_url, or to source_file_url when the original file is stored on the platform. Keep the passage and the label together: the label is built from the same source object the passage came from, so the two cannot drift apart. rerank_applied tells you whether the scores you display are reranker scores or vector scores.
Verify
Ask a question your sources answer and check that results is not empty and low_confidence is false. The same query on the Search & Test tab of Knowledge Management in the Control Room shows the same documents; an administrator or a Knowledge Admin can compare there.
Troubleshooting
- 422 naming
top_k: the value is above 100. - 422 naming a metadata key: the key is not declared filterable on any source in scope. An administrator declares filterable keys on the source.
- Results are empty and
results_withheldis above zero: the matching passages exist but the key's owner may not read their sources. low_confidenceis true: show the passages as a best-effort answer or ask the user to rephrase;subject_absentmeans the query names something none of the results contain.- 401 with
AUTH_ERRORalthough the key works for chat: the key lacks the Knowledge search scope, which the gateway checks while validating the key, so a missing scope reads as an invalid key.