Search a workspace

Files must be ingested before any of these work. They are not aliases — see Search methods and Choose the right tool.

Automatic search

One question, one answer. The service answers with a one-pass fact search or an agent that reads documents, queries tables, and selects documents from the metadata catalog, and returns that route’s result (with a catalog table when the agent answered from the catalog), plus which route it took. Single-shot: no session and no clarification question back. Pass mode fact or agent to run that route directly, with no routing step.

from ndi_sdk import NdiClient

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

See Automatic search, Python, and TypeScript.

QA

A conversation instead of a single query. Each turn runs the automatic search agent on its own; pass a result’s answer.session_id to ask a follow-up, and the agent may ask back on a genuinely ambiguous question. Chain follow-ups with that conversation’s session; do not share a session across unrelated questions.

from ndi_sdk import NdiClient
from ndi_sdk.models.jobs import AutomaticAgentResult

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

See QA, Python, and TypeScript.

Ground quote locations

Search does not wait for bounding boxes. After a succeeded answer, poll every id in its grounding_job_ids: on output for an automatic search answered by the fact route, on output.answer when the agent answered, on answer for a QA turn, and on the result itself for journal-entry testing. Do not POST /v1/ground for those evidences.

from ndi_sdk import NdiClient
from ndi_sdk.models.jobs import AutomaticAgentResult, AutomaticSearchResult, DeepSearchV2Result, IntelligentSearchResult

with NdiClient() as client:
    workspace_id = "550e8400-e29b-41d4-a716-446655440001"
    job = client.jobs.wait(
        client.search.automatic(
            workspace_id,
            query="What were total liabilities at year end?",
            wait_seconds=30,
        ).job_id,
        timeout=600,
    )
    if isinstance(job.result, AutomaticSearchResult):
        output = job.result.output
        answer = output.answer if isinstance(output, AutomaticAgentResult) else output
        if isinstance(answer, (DeepSearchV2Result, IntelligentSearchResult)):
            print(answer.answer)
            for ground_id in answer.grounding_job_ids or []:
                grounded = client.jobs.wait(ground_id, timeout=300)
                print(grounded.result)

An empty list means nothing was planned (postprocessing="none" or no groundable evidence). A missing field is a job from before this field existed — only then call Ground.

Catalog tables

When automatic search’s agent, or a QA turn, answers a filter, rank, or count question from the metadata catalog, the result carries a catalog table: typed columns, one row per matching catalog entry, and exact totals. Search returns matching catalog entries with identities established from the source data. Native register entries stay separate; supporting sections keep their own values and citations in components. total_matches counts entries and total_files counts their distinct source files. Both totals describe all confirmed matches before top-N and paging. Each row has a query-independent entry_id in the current catalog and a source_file_id for its supporting uploaded file. See the API reference for identity behavior on rebuild. You can also ask for fields to show beside each match. These columns carry requested=true. Missing output values remain unexamined without removing the entry; conditions that filter on those values must still be satisfied. A table carries up to 200 rows. When there are more, next_cursor pages the rest: client.search.filtered_page in Python, or POST /v1/workspaces/{id}/filtered-search with { "type": "page", "cursor": "..." }. A page is a new job and re-runs the table’s query against the current catalog.

from ndi_sdk import NdiClient
from ndi_sdk.models.jobs import AutomaticAgentResult, AutomaticSearchResult

with NdiClient() as client:
    workspace_id = "550e8400-e29b-41d4-a716-446655440001"
    job = client.jobs.wait(
        client.search.automatic(
            workspace_id,
            query="invoices over 10000 from Q4",
            mode="agent",
            wait_seconds=30,
        ).job_id,
        timeout=600,
    )
    if isinstance(job.result, AutomaticSearchResult) and isinstance(job.result.output, AutomaticAgentResult):
        catalog = job.result.output.catalog
        if catalog is not None:
            print(catalog.total_matches, catalog.total_files, catalog.exhaustive)
            if catalog.next_cursor:
                page = client.jobs.wait(client.search.filtered_page(workspace_id, cursor=catalog.next_cursor).job_id)
                print(page.result)

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

Journal-entry testing

Not retrieval. The run writes its own SQL over the ingested ledger tables and publishes every statement as a receipt, so each figure traces to the query behind it. Reach for it when the deliverable is a tested criterion rather than a cited passage.

Python
TypeScript
curl

from ndi_sdk import NdiClient

with NdiClient() as client:
    workspace_id = "550e8400-e29b-41d4-a716-446655440001"
    job = client.jobs.wait(
        client.search.je_testing(
            workspace_id,
            query="test whether any posted journal line was approved by its own preparer",
            paths=["ledger/journal.xlsx"],
        ).job_id
    )
    result = job.result
    print(result.answer)
    for figure in result.figures:
        print(figure.criterion, figure.count, "of", figure.population)

import { NdiClient, type models } from "ndi-sdk";

const client = new NdiClient({ api_key: process.env.NDI_API_KEY! });
const workspaceId = "550e8400-e29b-41d4-a716-446655440001";

const submitted = await client.search.jeTesting(workspaceId, {
  query: "test whether any posted journal line was approved by its own preparer",
  paths: ["ledger/journal.xlsx"],
});
const job = await client.jobs.wait(submitted.job_id);
const result = job.result as models.JetResult;
console.log(result.answer);

curl -s -X POST "$NDI_BASE_URL/v1/workspaces/$WS/je-testing" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"test whether any posted journal line was approved by its own preparer","paths":["ledger/journal.xlsx"]}'

effort on je-testing is the one knob (low / medium / high); omit it to take the deployment’s own floor. figures is the checkable half of the answer; sql_receipts is its working. exhausted means the step budget ran out before the procedure finished — a partial answer, not a failure. Full field reference: Python, TypeScript.

Deprecated: fact, deep, and filtered search

These keep working, as do their endpoints, until they are retired. New code should not start on them.

Deprecated	Use instead
Fact search: `client.search.fact`, `POST .../fact-search`	Automatic search with `mode="fact"`: the same pipeline, in the automatic result
Deep search: `client.search.deep`, `POST .../deep-search`	QA for a conversation; automatic search with `mode="agent"` for one question
Filtered search: `client.search.filtered`, `POST .../filtered-search` with `{ "type": "query" }`	Automatic search, whose agent answers from the catalog. Paging a catalog table is not deprecated

See Fact and deep search and Filtered search for their reference.

Coverage

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

Getting started

Guides

Agents

Concepts

Troubleshooting

Automatic search

QA

Ground quote locations

Catalog tables

Journal-entry testing

Deprecated: fact, deep, and filtered search

Coverage

​Automatic search

​QA

​Ground quote locations

​Catalog tables

​Journal-entry testing

​Deprecated: fact, deep, and filtered search

​Coverage

Automatic search

QA

Ground quote locations

Catalog tables

Journal-entry testing

Deprecated: fact, deep, and filtered search

Coverage