# Search with citations

Query the tenant's knowledge from your application, read each passage with the document it came from and a label to quote, and judge how much to trust the result set.

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.

Video: Search with citations (2:35), https://katonicdocsmedia.blob.core.windows.net/developers/search-with-citations/475216a63e4b/index.html

  
**Step 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.

  
**Step 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.

  
**Step 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.

   ```bash
   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.

   ```python
   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.

## Related

- Knowledge
- [Upload files and ingest](/developers/guides/upload-files-and-ingest)
- [Katonic MCP Server tools](/developers/libraries/mcp-server/tools)
- [Search and test your knowledge in the help centre](/knowledge/knowledge-bases/search-and-test)

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