TypeScript SDK - NDI Platform API

The NDI TypeScript SDK is a typed interface to the /v1 Platform API. It resolves credentials, mints idempotency keys, retries transient failures, and parses responses into TypeScript models.

Quick start

import { NdiClient, isParseResult } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("report.pdf");
const queued = await client.documents.parse(upload, { wait_seconds: 30 });
const job = await client.jobs.wait(queued.job_id, { timeout: 600 });

if (isParseResult(job.result)) {
  console.log(job.result.markdown);
}
// Returns: Job; job.result is a ParseResult on success

Key features

Typed end to end

Typed request options and response models. Unknown result variants load as UnknownResult, so an additive server change does not prevent the job from loading.

One async client

Every method returns a Promise. Share one NdiClient across requests and use Promise.all to collect concurrent work.

Jobs, not polling loops

Slow operations return a Job. Wait with jobs.wait, follow progress with jobs.events, or finish inline with wait_seconds.

Automatic retries

Backoff with jitter for 429, 5xx, and dropped connections. Job-creating calls mint idempotency keys so retries resolve to the original job.

Typed error hierarchy

Status failures expose the status code, error code, request ID, and retryability; job failures carry the terminal Job.

Zero runtime dependencies

Uses native fetch, FormData, and Blob. The package ships dual ESM and CommonJS builds and requires Node.js 20 or newer.

Installation

npm install ndi-sdk

Requires Node.js 20+. The package is ndi-sdk on npm. To upgrade, see Update the SDKs, CLI, and MCP.

Authentication

Set your API key as an environment variable:

export NDI_API_KEY="ndi_sk_..."

The SDK reads it automatically:

import { NdiClient } from "ndi-sdk";

const client = new NdiClient(); // reads process.env.NDI_API_KEY
client.close();

Or pass it explicitly:

import { NdiClient } from "ndi-sdk";

const client = new NdiClient({ api_key: "ndi_sk_..." });
client.close();

With neither, the constructor raises Error before the first request. base_url defaults to process.env.NDI_BASE_URL, then https://ndi-api.nace.ai; set it only to reach another host. Browser applications must pass credentials explicitly and should not expose a long-lived API key in client-side code.

Client options

new NdiClient({
  api_key?: string | null;
  base_url?: string | null;
  timeout?: number;
  retry_policy?: RetryPolicy;
  default_headers?: Record<string, string>;
  fetch?: typeof fetch;
})

import { NdiClient } from "ndi-sdk";

const client = new NdiClient({
  api_key: "ndi_sk_...",
  timeout: 120,
});

Option	Type	Default	Description
`api_key`	`string`	`$NDI_API_KEY`	Required if the env var is unset
`base_url`	`string`	`$NDI_BASE_URL` or production	Another host
`timeout`	`number`	`60`	Per-request seconds (does not include `wait_seconds`)
`retry_policy`	`RetryPolicy`	SDK default (3 attempts)	Retry budget — `max_attempts`, `initial_backoff`, `max_backoff`
`default_headers`	`Record<string, string>`	none	Extra headers on every request
`fetch`	`typeof fetch`	global `fetch`	Inject a custom transport

The option names use the SDK’s wire-style snake_case.

Core methods

Upload

Stage bytes for a granular operation. The handle is single-use and expires.

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("report.pdf");
// Returns: UploadResponse with upload_id and expires_at
console.log(upload.upload_id, upload.expires_at);

Upload documentation

Node and browser inputs, TTL, and when to use a workspace instead.

Parse

Turn a file into markdown, blocks, and optional chunks.

import { NdiClient, isParseResult } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("report.pdf");
const queued = await client.documents.parse(upload, { wait_seconds: 30 });
const job = await client.jobs.wait(queued.job_id);

if (isParseResult(job.result)) {
  console.log(job.result.document.markdown);
}
// Returns: Job; job.result is a ParseResult on success

Parse documentation

Parse modes, OCR, figures, chunking, and spreadsheet options.

Extract

Fill a JSON Schema from a document. Pass json_schema or a stored schema_id.

import { NdiClient, UnknownResult } from "ndi-sdk";

const schema = {
  type: "object",
  properties: {
    invoice_number: { type: "string" },
    total: { type: "number" },
  },
  required: ["invoice_number", "total"],
};

const client = new NdiClient();
const upload = await client.documents.createUpload("invoice.pdf");
const queued = await client.documents.extract(upload, {
  json_schema: schema,
  wait_seconds: 30,
});
const job = await client.jobs.wait(queued.job_id);

const result = job.result;
if (result?.result_type === "extract" && !(result instanceof UnknownResult)) {
  console.log(result.data);
}
// Returns: Job; job.result is an ExtractResult on success

Extract documentation

Schema design, field status, and citations.

Split

Cut a multi-document packet into classified segments.

import { NdiClient, UnknownResult } from "ndi-sdk";

const client = new NdiClient();
const packet = await client.documents.createUpload("vendor-packet.pdf");
const queued = await client.documents.split(packet, {
  classes: [
    { id: "invoice", label: "Invoice", description: "A supplier invoice" },
    { id: "receipt", label: "Receipt", description: "Evidence of payment" },
    { id: "purchase_order", label: "Purchase order" },
    { id: "bank_statement", label: "Bank statement" },
  ],
  wait_seconds: 30,
});
const job = await client.jobs.wait(queued.job_id);

const result = job.result;
if (result?.result_type === "split" && !(result instanceof UnknownResult)) {
  for (const segment of result.segments) {
    console.log(segment.split_class, segment.start_page, segment.end_page);
  }
}
// Returns: Job; job.result is a SplitResult on success

Split documentation

Classes, unknown and overlap policy, and split rules.

Classify

Label a whole document, or each page, against classes you define.

import { NdiClient, UnknownResult } from "ndi-sdk";

const client = new NdiClient();
const document = await client.documents.createUpload("mailroom-scan.pdf");
const queued = await client.documents.classify(document, {
  classes: [
    { id: "invoice", label: "Invoice" },
    { id: "receipt", label: "Receipt" },
    { id: "contract", label: "Contract" },
    { id: "bank_statement", label: "Bank statement" },
  ],
  granularity: "page",
  wait_seconds: 30,
});
const job = await client.jobs.wait(queued.job_id);

const result = job.result;
if (result?.result_type === "classify" && !(result instanceof UnknownResult)) {
  for (const unit of result.units) {
    console.log(unit.unknown, unit.labels);
  }
}
// Returns: Job; job.result is a ClassifyResult on success

Classify documentation

Criteria, subclasses, granularity, and unknown policy.

Ground

Pin quoted text to locations in the source document.

import { NdiClient, UnknownResult } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("report.pdf");
const queued = await client.documents.ground(upload, {
  targets: [
    { id: "total", text: "1,200.50" },
    { id: "fiscal_year", text: "year ended December 31, 2025" },
  ],
  wait_seconds: 30,
});
const job = await client.jobs.wait(queued.job_id);

const result = job.result;
if (result?.result_type === "ground" && !(result instanceof UnknownResult)) {
  for (const target of result.targets) {
    console.log(target.id, target.status, target.matches?.length ?? 0);
  }
}
// Returns: Job; job.result is a GroundResult on success

Ground documentation

Targets, match methods, and location shapes.

Workspaces

Build a durable corpus, then search it. Uploading registers a file; ingestion is a separate, billable operation.

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const workspace = await client.workspaces.create({ name: "fy25-audit" });
// Returns: Workspace with workspace_id

const uploaded = await client.uploadAndIngest(
  workspace.workspace_id,
  "report.pdf",
  { path: "reports/report.pdf" },
);
// Returns: UploadAndIngestResult with file, deduplicated, and ingestion_job
await client.jobs.wait(uploaded.ingestion_job.job_id, { timeout: 600 });

const submitted = await client.search.automatic(workspace.workspace_id, {
  query: "What were total liabilities at year end?",
  mode: "fact",
  wait_seconds: 30,
});
const answer = await client.jobs.wait(submitted.job_id, { timeout: 300 });
// Returns: succeeded Job; job.result is an AutomaticSearchResult
console.log(answer.result);

Workspaces documentation

Workspaces, files, ingestion, tools, and search.

Automatic search and QA

Ask one question with search.automatic, or hold a conversation with search.qa. Both return a Job.

import { NdiClient, UnknownResult } from "ndi-sdk";

const client = new NdiClient();
const workspaceId = "550e8400-e29b-41d4-a716-446655440001";
const job = await client.jobs.wait(
  (
    await client.search.automatic(workspaceId, {
      query: "Which subsidiaries missed covenant tests, and by how much?",
      mode: "agent",
      wait_seconds: 30,
    })
  ).job_id,
  { timeout: 600 },
);
const result = job.result;
if (result && !(result instanceof UnknownResult) && result.result_type === "automatic_search") {
  if (result.output.result_type === "automatic_agent") {
    console.log(result.output.answer.answer);
  }
}
// Returns: Job; result_type is automatic_search, whose output is the route's result

search.fact and search.deep are deprecated (@deprecated): they keep working until they are retired. See Search.

Automatic search

Routes, modes, structured answers, and catalog tables.

QA

Conversations, follow-ups, and clarifying questions.

Journal-entry testing

An audit procedure over an ingested ledger package, not a search preset. Returns a Job whose result is a JetResult. effort is the one knob; omit it to take the deployment’s own floor.

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

const client = new NdiClient();
const workspaceId = "550e8400-e29b-41d4-a716-446655440001";
const job = await client.jobs.wait(
  (
    await client.search.jeTesting(workspaceId, {
      query: "test whether any posted journal line was approved by its own preparer",
      paths: ["ledger/journal.xlsx"],
    })
  ).job_id,
);
const result = job.result as models.JetResult;
console.log(result.answer);
// Returns: Job; job.result is a JetResult on success

Journal-entry testing

Effort, file scope, SQL receipts, and figures.

Ledger understanding

Measures the ingested journal package — table roles, integrity, and optional GL parsing — and stores a report on the workspace. Returns a Job whose result is a LedgerUnderstandingResult.

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

const client = new NdiClient();
const workspaceId = "550e8400-e29b-41d4-a716-446655440001";
const job = await client.jobs.wait(
  (await client.workspaces.startLedgerUnderstanding(workspaceId)).job_id,
  { timeout: 3600 },
);
const result = job.result as models.LedgerUnderstandingResult;
console.log(result.report.stale, result.report.blocking);
const report = await client.workspaces.getLedgerUnderstanding(workspaceId);
console.log(report.tables.length, report.parsing);
// Returns: Job; job.result is a LedgerUnderstandingResult on success

Ledger understanding

Policy, reuse, the report, and in-progress conflicts.

Async and concurrency

Every method returns a Promise. Use Promise.all to fan out concurrent jobs and collect results together:

import { NdiClient, isParseResult } from "ndi-sdk";

const client = new NdiClient();

async function parsePdf(name: string): Promise<string | null> {
  const upload = await client.documents.createUpload(name);
  const queued = await client.documents.parse(upload, { wait_seconds: 30 });
  const job = await client.jobs.wait(queued.job_id, { timeout: 600 });
  return isParseResult(job.result) ? job.result.markdown : null;
}

// Fan out — runs both uploads and parses concurrently:
const [invoice, report] = await Promise.all([
  parsePdf("invoice.pdf"),
  parsePdf("report.pdf"),
]);
// Returns: [string | null, string | null]

JobFailedError rejects out of Promise.all. Pass { raise_on_failure: false } to jobs.wait and handle job.status yourself if you want partial failures to settle rather than reject.

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const [a, b] = await Promise.all([
  client.jobs.wait("job_aaa", { raise_on_failure: false }),
  client.jobs.wait("job_bbb", { raise_on_failure: false }),
]);
// Returns: [Job, Job] — check .status on each

client.close() is a no-op because the SDK does not own the global or injected fetch. If a custom transport holds resources, close those resources through the transport that created them.

Async and concurrency guide

Client lifetime, bounded concurrency, and partial failures.

Result types and narrowing

Every document operation returns a Job. job.result is typed as JobResult | null — a discriminated union. Use the exported type guards to narrow to the concrete variant:

import { NdiClient, isParseResult, isUploadFileResult, isIngestionResult } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("report.pdf");

// Parse → ParseResult
const parseJob = await client.jobs.wait(
  (await client.documents.parse(upload, { wait_seconds: 30 })).job_id,
  { timeout: 600 },
);
if (isParseResult(parseJob.result)) {
  const md: string | null = parseJob.result.markdown; // Returns: string | null
  const lane: string = parseJob.result.lane;          // Returns: string
}

// File upload → UploadFileResult
const uploadJob = await client.files.upload("ws_id", "report.pdf", {
  path: "reports/report.pdf",
});
if (isUploadFileResult(uploadJob.result)) {
  const fileId: string = uploadJob.result.file.file_id; // Returns: string
  const dedup: boolean = uploadJob.result.deduplicated;  // Returns: boolean
}

// Ingestion → IngestionResult
const ingestJob = await client.jobs.wait(
  (await client.ingestion.ingest("ws_id", { path_prefix: "reports/" })).job_id,
  { timeout: 600 },
);
if (isIngestionResult(ingestJob.result)) {
  console.log(ingestJob.result.files_ingested); // Returns: number
}

The SDK exports dedicated guards for ParseResult, UploadFileResult, and IngestionResult. Other known variants (split, extract, classify, ground, …) can be narrowed on result_type:

import { NdiClient, UnknownResult } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("invoice.pdf");
const queued = await client.documents.extract(upload, {
  json_schema: { type: "object", properties: { total: { type: "number" } } },
  wait_seconds: 30,
});
const job = await client.jobs.wait(queued.job_id);

const result = job.result;
if (result?.result_type === "extract" && !(result instanceof UnknownResult)) {
  const data = result.data; // Returns: Record<string, unknown> | undefined
}

UnknownResult catches any result_type the server returns that this SDK version does not know. Exclude it with instanceof UnknownResult before reading variant fields.

Errors

Typed errors expose status_code, code, retryable, and request_id.

import {
  AuthenticationError,
  JobFailedError,
  NdiClient,
  NdiStatusError,
} from "ndi-sdk";

const client = new NdiClient();
try {
  const upload = await client.documents.createUpload("report.pdf");
  const queued = await client.documents.parse(upload);
  await client.jobs.wait(queued.job_id);
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.log(err.status_code, err.request_id);
  } else if (err instanceof JobFailedError) {
    console.log(err.job.status, err.job.error);
  } else if (err instanceof NdiStatusError) {
    console.log(err.code, err.retryable, err.message);
  } else {
    throw err;
  }
}

Error handling guide

The full exception hierarchy, retry policy, and request IDs.

Exception	When
`AuthenticationError`	401
`PermissionDeniedError`	403
`NotFoundError`	404
`ConflictError`	409
`ResultExpiredError`	410
`RateLimitError`	429
`NdiTimeoutError`	HTTP timeout (abort signal fired)
`JobTimeoutError`	`jobs.wait` budget exhausted
`JobFailedError`	Job `failed` or `cancelled`

See Errors.

Pagination

iterAll walks cursor pages for workspaces, files, jobs, and domains. Access labels use iterAccessLabels. See Pagination.

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
for await (const ws of client.workspaces.iterAll()) {
  console.log(ws.workspace_id, ws.name); // Returns: string, string
}

Advanced

Timeouts and retries

import { NdiClient, RetryPolicy } from "ndi-sdk";

const client = new NdiClient({
  timeout: 120,                         // seconds per request
  retry_policy: RetryPolicy({
    max_attempts: 5,
    initial_backoff: 1.0,
    max_backoff: 30.0,
  }),
});

The SDK retries 429 and 5xx responses on idempotent requests (GET, PUT, DELETE, or any POST that carries an Idempotency-Key header — minted automatically by document operations). timeout applies per attempt, not over the full retry budget. Adjust wait_seconds when polling inline: timeout extends by wait_seconds for those requests.

Custom fetch and default headers

import { NdiClient } from "ndi-sdk";

const instrumentedFetch: typeof fetch = async (input, init) => {
  console.log("NDI request", input);
  return fetch(input, init);
};

const client = new NdiClient({
  // Inject any fetch-compatible transport.
  fetch: instrumentedFetch,
  default_headers: {
    "X-Correlation-Id": "req-abc123",
  },
});

default_headers are merged onto every request. The X-API-Key header is always set by the SDK and cannot be overridden via default_headers.

SSE job events

Stream status updates as a job runs using the server-sent events endpoint:

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const queued = await client.documents.parse(
  await client.documents.createUpload("report.pdf"),
);

for await (const event of client.jobs.events(queued.job_id)) {
  console.log(event.status, event.progress); // Returns: JobStatus, JobProgress | null
  if (event.status.is_terminal) {
    break;
  }
}

Resume from a checkpoint with { last_event_id: event.sequence.toString() }.

Legacy client

The client.legacy namespace wraps the original /api/v1 routes for callers who have not migrated to /v1. Upload a local file with client.legacy.upload. It returns a legacy upload handle with file_id, file_name and expires_at, not the /v1 UploadResponse with upload_id. Pass the handle to client.legacy.parse:

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.legacy.upload("report.pdf");
const job = await client.legacy.parse(upload);
// Returns: LegacyJob

toFileInput converts a source URL string or a legacy upload handle into a FileInput. A string is sent as source_url, so it must be an https://, s3://, or ndi://file/<id> URL, not a local path. Use the /v1 surface for new integrations.

Not wrapped

Call HTTP directly for these operations:

Operation	Endpoint
Catalog-table paging	`POST /v1/workspaces/{id}/filtered-search` with `{ "type": "page", "cursor": "..." }`
Run SQL	`POST /v1/workspaces/{id}/run-sql`
Request payload	`GET /v1/jobs/{id}/request`
Delete a job	`DELETE /v1/jobs/{id}`
Extraction-schema CRUD	`/v1/extraction-schemas`
Usage overview	`GET /v1/usage/overview`

effort is the knob on search.jeTesting only.

Next steps

Quickstart — full curl walkthrough
Parse guide — options, chunking, and spreadsheets
Workspace guide — ingest and search a corpus
Search guide — automatic search, QA, and journal-entry testing
Jobs and idempotency
MCP server — use NDI from Claude Code, Cursor, or opencode
NDI CLI — the same operations from the terminal

​Quick start

​Key features

Typed end to end

One async client

Jobs, not polling loops

Automatic retries

Typed error hierarchy

Zero runtime dependencies

​Installation

​Authentication

​Client options

​Core methods

​Upload

Upload documentation

​Parse

Parse documentation

​Extract

Extract documentation

​Split

Split documentation

​Classify

Classify documentation

​Ground

Ground documentation

​Workspaces

Workspaces documentation

​Automatic search and QA

Automatic search

QA

​Journal-entry testing

Journal-entry testing

​Ledger understanding

Ledger understanding

​Async and concurrency

Async and concurrency guide

​Result types and narrowing

​Errors

Error handling guide

​Pagination

​Advanced

​Timeouts and retries

​Custom fetch and default headers

​SSE job events

​Legacy client

​Not wrapped

​Next steps

Quick start

Key features

Installation

Authentication

Client options

Core methods

Upload

Parse

Extract

Split

Classify

Ground

Workspaces

Automatic search and QA

Journal-entry testing

Ledger understanding

Async and concurrency

Result types and narrowing

Errors

Pagination

Advanced

Timeouts and retries

Custom fetch and default headers

SSE job events

Legacy client

Not wrapped

Next steps