Workspaces

A workspace is persistent storage plus derived representations. Files remain until retention or deletion removes them. Uploading creates a file record; ingestion is the separate, billable operation that makes the file searchable.

Create

Choose the workspace name, domain, access policy, retention, currency, knowledge-graph, and ledger-understanding policy.

Upload

Add source files at stable paths. Large SDK uploads automatically use resumable sessions.

Ingest

Build derived files, metadata, search indexes, and optional graph inputs.

Search and analyze

Use automatic search, QA, file QA, or table QA.

Basic usage

import { NdiClient } from "ndi-sdk";

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

await client.jobs.wait(
  (
    await client.files.upload(workspace.workspace_id, "report.pdf", {
      path: "reports/report.pdf",
    })
  ).job_id,
);
// Returns: succeeded Job; job.result is an UploadFileResult

await client.jobs.wait(
  (
    await client.ingestion.ingest(workspace.workspace_id, { path_prefix: "reports/" })
  ).job_id,
  { timeout: 600 },
);
// Returns: succeeded Job; job.result is an IngestionResult

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);

client.uploadAndIngest(...) combines the upload and ingestion calls for one file. Files at or above 32 MiB automatically use resumable upload sessions.

Create a workspace

Method signature

workspaces.create(opts: {
  name: string;
  domain_slug?: string;
  domain_version?: number;
  access?: AccessConfig;
  retention_policy?: RetentionPolicy;
  knowledge_graph?: KnowledgeGraphConfig;
  currency?: CurrencyPolicy;
  ledger_understanding?: LedgerUnderstandingConfig;
  global_context?: string;
}): Promise<Workspace>

Parameters

Parameter	Required	Description
`name`	Yes	Human-readable name. Must be non-blank, 1–200 characters, with no control characters
`domain_slug`	No	Domain vocabulary. Defaults to `generic`
`domain_version`	No	Pin a published domain version. Omit for the latest
`access`	No	Frozen access-label set and optional default label
`retention_policy`	No	Derived, source, and job-payload lifetimes
`knowledge_graph`	No	Automatic-build and exclusion policy
`currency`	No	Currency used to disambiguate symbols such as `$`
`ledger_understanding`	No	When ingestion should measure the journal package, and whether to parse journals
`global_context`	No	Standing background for every query. A je-testing or search call that omits `context` runs with it

Returns

A Workspace containing the generated ID, name, resolved domain/version, configuration, status, purpose, and timestamps. It is ready for uploads immediately; there is no activation step. Workspace names may contain spaces and dashes. A second active workspace with the same owner and name returns workspace_name_taken.

Configure access labels

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const workspace = await client.workspaces.create({
  name: "fy25-audit",
  access: {
    labels: [
      { name: "financial", description: "Financial documents available to the finance team" },
      { name: "audit_only", description: "Restricted audit evidence" },
    ],
    default_label: "financial",
  },
});
// Returns: Workspace with the frozen access policy

Create labels in the organization catalog first, then freeze the selected {name, description} objects onto the workspace. An empty label list disables access-label filtering. With a non-empty list, default_label must name one of those labels. See Access labels.

Configure retention

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const workspace = await client.workspaces.create({
  name: "temporary-review",
  retention_policy: {
    derived_ttl_days: 90,
    source_ttl_days: 365,
    job_ttl_days: 30,
  },
});
// Returns: Workspace with the selected retention policy

Retention is chosen at creation. Derived TTL, source TTL, and job-payload TTL are separate; zero or null semantics depend on the field. See File lifecycle before setting them.

Configure currency and knowledge graph

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const workspace = await client.workspaces.create({
  name: "canada-fy25",
  currency: { default: "CAD" },
  knowledge_graph: {
    auto_build: false,
    exclude_path_prefixes: ["drafts/"],
    exclude_categories: ["administrative"],
  },
});
// Returns: Workspace with CAD disambiguation and graph exclusions

Knowledge-graph builds are billable and are not implied by ingestion unless auto_build: true.

Upload files

files.upload writes a persistent source at a workspace path:

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

const client = new NdiClient();
const workspace = await client.workspaces.create({ name: "upload-demo" });
const job = await client.jobs.wait(
  (
    await client.files.upload(workspace.workspace_id, "invoice.pdf", {
      path: "invoices/2026/invoice.pdf",
      labels: { source: "email" },
      on_conflict: "new_version",
    })
  ).job_id,
);
// Returns: succeeded Job; job.result is an UploadFileResult
if (isUploadFileResult(job.result)) {
  console.log(job.result.file.file_id, job.result.deduplicated);
}

The workspace path is required and remains the file’s identity. On conflict, reject fails while new_version replaces the current bytes and preserves version metadata. The labels mapping on a file is caller-defined metadata. It is separate from the workspace access-label policy. An unsupported source throws InvalidRequestError with code === ErrorCode.UNSUPPORTED_FILE_TYPE before a workspace file is created. uploadAndIngest stops at the same boundary and does not queue ingestion. Use Format support as the source of truth instead of maintaining a client-side extension list. Files at or above 32 MiB automatically use resumable upload sessions. Call files.uploadChunked directly only when you want that behavior below the automatic threshold.

Upload from a URL

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const workspace = await client.workspaces.create({ name: "url-upload-demo" });
const queued = await client.files.uploadFromUrl(workspace.workspace_id, {
  path: "reports/annual-report.pdf",
  url: "https://example.com/annual-report.pdf",
  file_name: "annual-report.pdf",
});
// Returns: Job; NDI fetches and stores the source bytes

Use a presigned URL for private storage. NDI must be able to reach the URL.

Upload from a browser

Your backend can mint a short-lived upload grant without exposing its API key:

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const workspace = await client.workspaces.create({ name: "browser-upload-demo" });
const grant = await client.files.createUploadGrant(workspace.workspace_id, {
  path: "incoming/report.pdf",
  max_bytes: 25_000_000,
});
// Returns: UploadGrantResponse with token, upload_url, and expires_at

The browser redeems the token in X-Upload-Token. total_size_bytes can pin the expected upload size and ttl_seconds can shorten the grant lifetime. See Upload grants.

Large uploads

Resume interrupted uploads and understand session tokens, parts, and completion.

File lifecycle

Understand discovered, ingested, stale, expired, replacement, and deletion states.

Inspect and manage files

Method	Purpose
`files.list` / `files.iterAll`	Filter files by path, ingestion status, category, type, or modification time
`files.get`	Read the file record and short-lived source download URLs
`files.metadata`	Read ingestion-derived metadata, outputs, and representation status
`files.getOutput` / `files.listOutputMembers`	Presign and browse derived-file outputs
`files.versions`	Read version metadata, newest first
`files.replace`	Replace bytes in place and mark the file stale
`files.delete`	Cascade-delete the file and its derived representations as a job
`files.artifactContent`	Read current workspace artifact bytes by exact path

Use files.metadata(workspace_id, file_id).then(m => m.representations) when you need to know whether a specific file is searchable now.

Ingest files

Uploading alone does not make a file searchable. Ingest by file IDs, by path prefix, or across the entire workspace:

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

const client = new NdiClient();
const workspace = await client.workspaces.create({ name: "ingestion-demo" });
const uploadJob = await client.jobs.wait(
  (
    await client.files.upload(workspace.workspace_id, "report.pdf", {
      path: "reports/report.pdf",
    })
  ).job_id,
);

const fileId = isUploadFileResult(uploadJob.result) ? uploadJob.result.file.file_id : null;

const queued = await client.ingestion.ingest(workspace.workspace_id, {
  file_ids: fileId ? [fileId] : undefined,
  wait_seconds: 30,
});
const job = await client.jobs.wait(queued.job_id, { timeout: 600 });
// Returns: succeeded Job; job.result is an IngestionResult

if (isIngestionResult(job.result)) {
  console.log(job.result.files_ingested);
  console.log(job.result.files_skipped);
  console.log(job.result.files_empty);
  console.log(job.result.files_failed);
  for (const outcome of job.result.outcomes) {
    console.log(outcome.path, outcome.status);
  }
}

Pass either file_ids or path_prefix, never both. Omit both to ingest the whole workspace. For routine refreshes, combine a prefix with stale_only: true. One corrupt file appears as a failed outcome on a succeeded job. It does not fail a folder-wide ingestion. A job where every attempted file failed is failed. The code is taken from the files, and error.detail lists them. Partial failures stay outcomes on a succeeded job.

Upload and ingest one file

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

const client = new NdiClient();
const workspace = await client.workspaces.create({ name: "combined-demo" });
const result = await client.uploadAndIngest(workspace.workspace_id, "report.pdf", {
  path: "reports/report.pdf",
  wait_seconds: 30,
});
// Returns: UploadAndIngestResult with file, deduplicated, ingestion_job

try {
  const job = await client.jobs.wait(result.ingestion_job.job_id, { timeout: 600 });
  if (isIngestionResult(job.result)) {
    console.log(job.result.files_ingested);
  }
} catch (error) {
  if (!(error instanceof JobFailedError)) {
    throw error;
  }
  // Every attempted file failed. There is no result. Reasons are on error.detail.
  console.log(error.job.error?.code, error.job.error?.detail);
}

This convenience still performs two API operations. Use the explicit methods when uploading several files before one ingestion run.

Reconcile external storage changes

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.ingestion.reconcile(workspaceId, {
      path_prefix: "reports/",
      auto_ingest: true,
    })
  ).job_id,
  { timeout: 600 },
);
// Returns: succeeded Job; job.result is a ReconciliationResult
if (job.result?.result_type === "reconciliation" && !(job.result instanceof UnknownResult)) {
  console.log(job.result.discovered, job.result.marked_stale);
}

Reconciliation detects ledger drift. With auto_ingest: true, it chains a separate ingestion job for discovered or stale files.

Search and analyze

Files must finish ingestion before tools and search can use their derived representations.

Need	SDK method	Return
Ask one document/image/media question	`client.tools.qaFile`	Inline `QaFileResponse`
Ask across selected tables	`client.tools.queryTables`	Inline `QueryTablesResponse`
One question: a fact lookup, research, or a filtered list or count	`client.search.automatic`	`Job`
A conversation with follow-ups	`client.search.qa`	`Job`
Deprecated: `client.search.fact`, `client.search.deep`	Use the two rows above	`Job`

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const workspaceId = "550e8400-e29b-41d4-a716-446655440001";
const response = await client.tools.qaFile(workspaceId, {
  path: "reports/report.pdf",
  query: "What was revenue by segment?",
});
// Returns: QaFileResponse with the answer and its citations
console.log(response.answer);
for (const citation of response.citations ?? []) {
  console.log(citation.path, citation.snippet);
}

Use Search methods to choose a method.

QA and follow-up threads

search.qa asks one turn of a conversation. The result’s answer.session_id continues it as a follow-up:

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

const client = new NdiClient();
const workspaceId = "550e8400-e29b-41d4-a716-446655440001";

// First question
const firstJob = await client.jobs.wait(
  (
    await client.search.qa(workspaceId, {
      query: "What are total liabilities at year end?",
      wait_seconds: 30,
    })
  ).job_id,
  { timeout: 600 },
);
// Returns: Job with an AutomaticAgentResult

const sessionId =
  firstJob.result?.result_type === "automatic_agent" && !(firstJob.result instanceof UnknownResult)
    ? firstJob.result.answer.session_id
    : null;

// Follow-up in the same conversation
if (sessionId) {
  const followUpJob = await client.jobs.wait(
    (
      await client.search.qa(workspaceId, {
        query: "Break that down by segment.",
        session_id: sessionId,
        wait_seconds: 30,
      })
    ).job_id,
    { timeout: 600 },
  );
  // Returns: the follow-up turn's AutomaticAgentResult
}

Automatic search

Routes, modes, structured answers, and catalog tables.

QA

Conversations, follow-ups, and clarifying questions.

Build a knowledge graph

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

const client = new NdiClient();
const workspaceId = "550e8400-e29b-41d4-a716-446655440001";
const queued = await client.ingestion.buildKnowledgeGraph(workspaceId, {
  wait_seconds: 30,
});
const job = await client.jobs.wait(queued.job_id, { timeout: 600 });
// Returns: succeeded Job; job.result is a KnowledgeGraphBuildResult
if (job.result?.result_type === "kg_build" && !(job.result instanceof UnknownResult)) {
  console.log(job.result.node_count, job.result.edge_count);
}

Graph construction is corpus-wide. force: true clears the durable graph store before rebuilding; omit it for normal incremental work.

Knowledge graph guide

Configure automatic builds and exclusions, then inspect, search, and traverse the graph.

List, inspect, and update

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
for await (const workspace of client.workspaces.iterAll({ name_contains: "audit" })) {
  const stats = await client.workspaces.stats(workspace.workspace_id);
  // Returns: WorkspaceStats
  console.log(workspace.workspace_id, workspace.name, stats.files_total);
  console.log(stats.files_by_ingestion_status);
}

files_by_ingestion_status is the completeness signal: stale files need re-ingestion; expired files need their derived representations rebuilt. Only the retention, knowledge-graph, currency, and ledger-understanding blocks and the global context are mutable:

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const workspaceId = "550e8400-e29b-41d4-a716-446655440001";
const workspace = await client.workspaces.get(workspaceId);
const updated = await client.workspaces.update(workspaceId, {
  knowledge_graph: {
    auto_build: true,
    exclude_path_prefixes: workspace.knowledge_graph?.exclude_path_prefixes ?? [],
    exclude_categories: workspace.knowledge_graph?.exclude_categories ?? [],
  },
});
// Returns: updated Workspace

Updating replaces each supplied block whole. Read the existing block and send back every field you want to preserve. Retention edits apply to existing data differently per lifetime: a changed derived_ttl_days recomputes the expiry of files already ingested (clearing it removes their expiry), source_ttl_days is evaluated at each sweep so it applies to existing files, and job_ttl_days applies only to jobs created afterwards. Set the global context once and every je-testing or search call that omits context runs with it:

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const workspaceId = "550e8400-e29b-41d4-a716-446655440001";
await client.workspaces.update(workspaceId, {
  global_context: "Journal ID = period + subperiod + Journal Cd + posting sequence number",
});
const job = await client.search.jeTesting(workspaceId, {
  query: "Test for out-of-hours postings.",
});
// Runs with the global context; pass context: "" to run with none.

global_context: "" clears it.

Delete a workspace

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

const client = new NdiClient();
const workspace = await client.workspaces.create({ name: "delete-demo" });
const queued = await client.workspaces.delete(workspace.workspace_id, {
  confirm_name: workspace.name,
  wait_seconds: 30,
});
const job = await client.jobs.wait(queued.job_id, { timeout: 600 });
// Returns: succeeded Job; job.result is a WorkspaceDeleteResult
if (job.result?.result_type === "workspace_delete" && !(job.result instanceof UnknownResult)) {
  console.log(job.result.verified, job.result.files_deleted);
}

confirm_name must match exactly. Deletion cascades through source files, derived outputs, index rows, and graph data and cannot be undone. Platform-managed workspaces with a non-null purpose cannot be deleted.

Error handling

import { NdiClient, ConflictError, InvalidRequestError } from "ndi-sdk";

const client = new NdiClient();
try {
  const workspace = await client.workspaces.create({ name: "fy25-audit" });
  // Returns: Workspace, or throws for a conflict/invalid request
} catch (err) {
  if (err instanceof ConflictError) {
    console.log(err.code, err.message);
  } else if (err instanceof InvalidRequestError) {
    console.log(err.code, err.message);
  }
}

Common errors include unsupported_file_type, workspace_name_taken, path conflicts, invalid access labels, tools called before ingestion, and a deletion confirmation that does not match the workspace name.

Best practices

Separate upload from ingestion

Upload files first, then ingest a batch by IDs or path prefix to avoid one ingestion run per file.

Use stable paths

Treat the workspace path as the durable file identity and use new_version for replacements.

Inspect every outcome

Folder ingestion can succeed while individual files report failed outcomes.

Read coverage

Search and tool responses disclose when access labels withheld matching candidates.

Get started

Core methods

Async and utilities

Basic usage

Create a workspace

Method signature

Parameters

Returns

Configure access labels

Configure retention

Configure currency and knowledge graph

Upload files

Upload from a URL

Upload from a browser

Large uploads

File lifecycle

Inspect and manage files

Ingest files

Upload and ingest one file

Reconcile external storage changes

Search and analyze

QA and follow-up threads

Automatic search

QA

Build a knowledge graph

Knowledge graph guide

List, inspect, and update

Delete a workspace

Error handling

Best practices

Separate upload from ingestion

Use stable paths

Inspect every outcome

Read coverage

Next steps

​Basic usage

​Create a workspace

​Method signature

​Parameters

​Returns

​Configure access labels

​Configure retention

​Configure currency and knowledge graph

​Upload files

​Upload from a URL

​Upload from a browser

Large uploads

File lifecycle

​Inspect and manage files

​Ingest files

​Upload and ingest one file

​Reconcile external storage changes

​Search and analyze

​QA and follow-up threads

Automatic search

QA

​Build a knowledge graph

Knowledge graph guide

​List, inspect, and update

​Delete a workspace

​Error handling

​Best practices

Separate upload from ingestion

Use stable paths

Inspect every outcome

Read coverage

​Next steps

Basic usage

Create a workspace

Method signature

Parameters

Returns

Configure access labels

Configure retention

Configure currency and knowledge graph

Upload files

Upload from a URL

Upload from a browser

Inspect and manage files

Ingest files

Upload and ingest one file

Reconcile external storage changes

Search and analyze

QA and follow-up threads

Build a knowledge graph

List, inspect, and update

Delete a workspace

Error handling

Best practices

Next steps