Skip to main content

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.

VideoSearch with citations2:35

Recorded on .

  1. 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.

  2. List the sources and search

    GET /public/v1/sources lists the sources the key can search, with their sync status and document counts. Send POST /public/v1/search with a query from your application for the ranked passages.

  3. Cite each passage

    Quote each hit's source_label and link its document_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/sources lists them with their sync status and document counts, if you want to search a subset by id.

Search and cite​

  1. Ask the question. query is the only required field. top_k caps the number of passages at 100, and rerank re-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}'
  2. Read each hit. Every entry of results carries the passage (content), its score, where it sits in the document (heading_path, page_number, chunk_index), how it was found (retrieval_source: vector, graph or graph_boost) and a source object with document_title, document_url, source_file_url, source_name and connector_type. source_label is the first of the document title, the source name, the document URL and the file URL that has a value.

    import requests

    r = 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 ''}")
  3. Judge the result set before you show it. low_confidence is true when no result cleared the confidence threshold; low_confidence_reason says why (below_gate, subject_absent or below_floor), and best_score, threshold_applied and best_score_scale give the numbers. results_withheld counts passages dropped because the caller may not read them. An empty list with empty_reason set to timeout means the search budget ran out at timed_out_stage, not that nothing matched.

  4. Narrow or widen the search. source_ids limits the search to named sources; heading_path_contains, page_range, created_after and created_before filter passages; metadata_filters matches document metadata, but each key must be declared filterable on a source in scope or the call fails with 422 naming the key. expand_context adds the neighbouring passages as context_window, graph_expansion brings in passages linked through the knowledge graph, and hyde embeds 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_withheld is above zero: the matching passages exist but the key's owner may not read their sources.
  • low_confidence is true: show the passages as a best-effort answer or ask the user to rephrase; subject_absent means the query names something none of the results contain.
  • 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, so a missing scope reads as an invalid key.

Describes the platform as of .

Was this page helpful?