Search a workspace

Files must be ingested before any of these work. They are not aliases — see Search methods.

Hybrid search

Inline, not a job. Ranked snippets from BM25 + dense vectors.

Python
TypeScript
curl

from ndi_sdk import NdiClient

with NdiClient() as client:
    workspace_id = "550e8400-e29b-41d4-a716-446655440001"
    hits = client.tools.hybrid_search(
        workspace_id,
        query="revenue by segment",
        k=10,
        path_prefix="reports/",
    )
    for hit in hits.hits:
        print(hit.path, hit.snippet)
    print(hits.coverage)

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const workspaceId = "550e8400-e29b-41d4-a716-446655440001";
const hits = await client.tools.hybridSearch(workspaceId, {
  query: "revenue by segment",
  k: 10,
  path_prefix: "reports/",
});
for (const hit of hits.hits ?? []) {
  console.log(hit.path, hit.snippet);
}

curl -s -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 by segment","k":10,"path_prefix":"reports/"}'

Fact search

One-pass lookup. Returns a job with an answer and evidence.

from ndi_sdk import NdiClient

with NdiClient() as client:
    workspace_id = "550e8400-e29b-41d4-a716-446655440001"
    job = client.jobs.wait(
        client.search.fact(
            workspace_id,
            query="What were total liabilities at year end?",
            wait_seconds=30,
        ).job_id,
        timeout=300,
    )
    print(job.result)

Deep search

Agent loop. One question per session_id. Chain follow-ups with that turn’s session; do not share a session across unrelated questions.

from ndi_sdk import NdiClient

with NdiClient() as client:
    workspace_id = "550e8400-e29b-41d4-a716-446655440001"
    first = client.jobs.wait(
        client.search.deep(
            workspace_id,
            query="Which subsidiaries missed covenant tests?",
            wait_seconds=30,
        ).job_id,
        timeout=600,
    )
    session_id = first.result.session_id
    follow = client.jobs.wait(
        client.search.deep(
            workspace_id,
            query="Show the supporting numbers for the first one.",
            session_id=session_id,
            wait_seconds=30,
        ).job_id,
        timeout=600,
    )
    print(follow.result)

The SDK has no tier argument. Deep search is not chat.

Filtered search

Catalog-first filter / rank / count. Python SDK only — client.search.filtered and client.search.filtered_page. TypeScript callers POST /v1/workspaces/{id}/filtered-search with { "type": "query", ... } then { "type": "page", "cursor": "..." }.

from ndi_sdk import NdiClient

with NdiClient() as client:
    workspace_id = "550e8400-e29b-41d4-a716-446655440001"
    job = client.jobs.wait(
        client.search.filtered(
            workspace_id,
            query="invoices over 10000 from Q4",
            wait_seconds=30,
        ).job_id
    )
    print(job.result.total_matches, job.result.exhaustive)
    if job.result.next_cursor:
        page = client.jobs.wait(
            client.search.filtered_page(
                workspace_id,
                cursor=job.result.next_cursor,
            ).job_id
        )
        print(page.result)

Read exhaustive before treating a result as a census. catalog_drifted on a later page means the catalog changed since the first page.

Coverage

Every tool response can include coverage.restricted_candidates and labels_required when your key cannot see every matching file. See Access labels.

Getting started

Guides

Concepts

Python SDK

TypeScript SDK

Agents

Troubleshooting

Hybrid search

Fact search

Deep search

Filtered search

Coverage

​Hybrid search

​Fact search

​Deep search

​Filtered search

​Coverage

Hybrid search

Fact search

Deep search

Filtered search

Coverage