> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usehasp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# knowledge.search

> Governed retrieval over your org's uploaded knowledge base — PHI-redacted at ingestion, citation-persisted.

`knowledge.search` performs a governed similarity search over your organization's uploaded knowledge base documents. The model receives the top-matching excerpts, ranked by similarity, with citations back to the source document. HASP owns the embedding pipeline end-to-end — chunking, embedding, and vector search all happen inside HASP's infrastructure.

Document RAG is off by default per org. An admin must upload documents and enable retrieval under **Settings → Knowledge Base** before `knowledge.search` is available to the model.

## PHI handling

Unlike `web.search`, PHI handling for `knowledge.search` happens at two different points:

1. **At ingestion** — every uploaded document is scanned and PHI is redacted before it is chunked and embedded. This is unconditional: there is no setting that disables it, and no re-identification path exists for retrieved chunks. Only the redacted text is ever stored or searched.
2. **At query time** — the search query itself is scanned and redacted before it reaches the embedding provider, the same posture `web.search` applies to outbound queries.

Because ingested content is always redacted first, retrieved excerpts can never surface PHI, regardless of what a user searches for.

## Billing

Document RAG has no dedicated per-call surcharge (unlike `web.search`'s flat credit fee). Cost is metered through your existing allotments:

* **Storage** — cumulative bytes of uploaded documents and their embeddings.
* **AI Credits** — the embedding call at ingestion time, and normal input-token cost for retrieved excerpts injected into context.

## Input parameters

| Parameter | Type   | Required | Description                                         |
| --------- | ------ | -------- | --------------------------------------------------- |
| `query`   | string | Yes      | The search query to run against the knowledge base. |

The number of chunks returned per query is capped by your org's `max_chunks_per_retrieval` setting (**Settings → Knowledge Base**), not a per-call parameter.

## Output

Matching chunks are assembled into the model's context as `[n] {document title}` followed by the chunk's redacted text, using the same `[n]` citation-marker convention as `web.search`. If nothing matches, the model receives a "no matching knowledge base content found" result.

## Citations

Retrieved chunks are persisted as citations linked to the conversation message, distinguished from web citations by `kind: "document"`. A document citation has no external URL — only the source document's title and rank. Citations survive page refresh and are available in the [Audit endpoint](/ai-api/control/audit).

## Uploading documents

Documents are uploaded through the Public API's Knowledge Base endpoints, gated by the `knowledge:read` scope for listing and the `ai:embeddings` scope for uploads and deletes. Uploads are processed asynchronously: the endpoint returns immediately, and the document's `status` field (`pending` → `extracting` → `chunking` → `embedding` → `ready`, or `failed`) reflects ingestion progress. Uploading the same file content twice for the same org is a no-op — HASP deduplicates by content hash and does not re-embed.

Accepted formats: PDF, DOCX, TXT, Markdown, HTML, and common image formats (scanned pages are extracted via HASP's self-hosted OCR sidecar — no third-party OCR provider is involved).

## Error codes

| Code                     | Description                                                                                                    |
| ------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `RAG_RETRIEVAL_DISABLED` | Document RAG is not enabled for this org (the org has not turned on the **Settings → Knowledge Base** toggle). |

See [Errors](/ai-api/reference/errors) for the full error envelope shape.