Search tool

​

Hybrid search

POST /v1/workspaces/{workspace_id}/tools/hybrid-search

{
  "query": "revenue recognition policy",
  "k": 10,
  "path_prefix": null,
  "categories": null
}

• query (required, max 4096 chars) — Search query.
• k (optional, default 10, max 100) — Number of hits to return.
• path_prefix (optional) — Restrict to files under this folder prefix.
• categories (optional) — Restrict to files assigned these document categories (from classification).

curl -X POST "$NDI_BASE_URL/v1/workspaces/$WS/tools/hybrid-search" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "revenue recognition policy", "k": 5}'

{
  "hits": [
    {
      "file_id": "550e8400-e29b-41d4-a716-446655440004",
      "path": "reports/annual-report-2025.pdf",
      "locator": {"kind": "text_range", "page": 12, "char_start": 430, "char_end": 560},
      "relevance_score": 0.92,
      "snippet": "Revenue is recognized when control of the promised goods or services is transferred to customers...",
      "why": "Direct match for revenue recognition criteria",
      "component": "revenue_recognition_policy"
    }
  ],
  "candidates_seen": 47,
  "truncated": false,
  "coverage": {"restricted_candidates": 0, "labels_required": []}
}

• hits — Ordered by score. Each Evidence item: file_id, path, locator (required — page/position in the source), relevance_score, snippet (verbatim passage), why (retrieval rationale), component (which public component of the file the hit came from — a spreadsheet tab name or a split document’s section; null for single-component files or when attribution is unavailable). Act on a hit by passing component straight to qa-file / read-file as component= (with pages from the locator for documents).
• candidates_seen — Pre-access-filter count; compare to hits length to tell when the access gate truncated results.
• truncated — true when the index found more than k candidates before access filtering.
• coverage — Labels required to see withheld candidates.

​

Choosing a search method

​

Errors

• workspace_not_found (404) — No such workspace.
• invalid_request (422) — query is empty, k is out of range, or both path_prefix and categories produce an empty scope.