Document Search

Document search is designed so users can inspect matching text before opening a file.

All document cards, passage matches, and snippets are filtered by the caller's current final Document permissions before they can influence the response. Organization entitlement ceilings and PAT scopes can narrow those permissions; an unavailable Document ceiling removes existing Documents from search without deleting them.

Recommended UX Flow

1. Call POST /v1/search/suggestions while the user types.
2. Call POST /v1/search when the user submits or pauses.
3. Render Document and DocumentContent results with the returned snippet.
4. Show source.pageNumber when present.
5. Track the response searchId.
6. Open the full document only when the user explicitly chooses to.
7. Report preview and open events with POST /v1/search/interactions.

Rendering Document Results

For document-heavy views, prefer this layout:

• title: original filename
• subtitle: object key or storage path context
• preview: snippet
• context badge: Page {source.pageNumber} when available

This gives users enough context to decide whether a document is relevant without downloading or opening it first.

When the user opens the full document, report that interaction against the original searchId. That data is what later lets ranking favor results that are actually opened instead of merely shown.

Rendering DocumentContent Results

Use DocumentContent results when you want to emphasize the exact matching passage:

• keep the parent filename visible
• display the excerpt from snippet
• route to a document preview or viewer anchored to the matching page if your client supports it

Operational Notes

Document previews depend on indexed passage text. If preview text is missing:

• confirm the document is a supported text-extraction format
• trigger POST /v1/search/index/documents/{documentId}
• check GET /v1/search/index/status

For large legacy datasets, queue a backfill so older documents receive passage previews as well.

If clusters, locations, annotations, or document cards themselves are missing from universal search, run the asset backfill endpoint in addition to the document passage backfill.

After a permission or entitlement change, a temporary reduction in search results can also mean the authorization projection is still converging. The service fails stale index data closed, so clients should retry rather than assuming an older result remains accessible.

Admins can queue POST /v1/search/index/assets/authorization/organizations/{organizationId}/repair when one organization's indexed authorization metadata remains stale. This restamps both asset and passage indices. If the underlying resource projection is missing or obsolete, run the asset and document passage backfills instead.