Create a workspace - NDI Platform API

A workspace is persistent storage plus derived outputs. Uploading registers a ledger row. Ingestion is a separate, billable call that builds the search index and metadata catalog.

Python
TypeScript
curl

from ndi_sdk import NdiClient

with NdiClient() as client:
    workspace = client.workspaces.create(name="fy25-audit")
    upload = client.jobs.wait(
        client.files.upload(
            workspace.workspace_id,
            "report.pdf",
            path="reports/report.pdf",
        ).job_id
    )
    client.jobs.wait(
        client.ingestion.ingest(
            workspace.workspace_id,
            path_prefix="reports/",
        ).job_id,
        timeout=600,
    )
    answer = client.jobs.wait(
        client.search.automatic(
            workspace.workspace_id,
            query="What were total liabilities at year end?",
            mode="fact",
            wait_seconds=30,
        ).job_id,
        timeout=300,
    )
    print(answer.result)

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const workspace = await client.workspaces.create({ name: "fy25-audit" });
await client.jobs.wait(
  (
    await client.files.upload(workspace.workspace_id, "report.pdf", {
      path: "reports/report.pdf",
    })
  ).job_id,
);
await client.jobs.wait(
  (await client.ingestion.ingest(workspace.workspace_id, { path_prefix: "reports/" })).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 });
console.log(answer.result);

WS=$(curl -s -X POST "$NDI_BASE_URL/v1/workspaces" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"fy25-audit","domain_slug":"generic"}' | jq -r '.workspace_id')

UPLOAD_JOB=$(curl -s -X POST "$NDI_BASE_URL/v1/workspaces/$WS/files" \
  -H "X-API-Key: $NDI_API_KEY" \
  -F "file=@report.pdf" \
  -F 'metadata={"path":"reports/report.pdf"}')
FILE_JOB_ID=$(echo "$UPLOAD_JOB" | jq -r '.job_id')

STATUS=$(curl -s "$NDI_BASE_URL/v1/jobs/$FILE_JOB_ID" -H "X-API-Key: $NDI_API_KEY" | jq -r '.status')
until [[ "$STATUS" == "succeeded" || "$STATUS" == "failed" || "$STATUS" == "cancelled" ]]; do
  sleep 3
  STATUS=$(curl -s "$NDI_BASE_URL/v1/jobs/$FILE_JOB_ID" -H "X-API-Key: $NDI_API_KEY" | jq -r '.status')
done

INGEST_JOB=$(curl -s -X POST "$NDI_BASE_URL/v1/workspaces/$WS/ingestions" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"selection":{"type":"path_prefix","path_prefix":"reports/"}}' | jq -r '.job_id')

STATUS=$(curl -s "$NDI_BASE_URL/v1/jobs/$INGEST_JOB" -H "X-API-Key: $NDI_API_KEY" | jq -r '.status')
until [[ "$STATUS" == "succeeded" || "$STATUS" == "failed" || "$STATUS" == "cancelled" ]]; do
  sleep 3
  STATUS=$(curl -s "$NDI_BASE_URL/v1/jobs/$INGEST_JOB" -H "X-API-Key: $NDI_API_KEY" | jq -r '.status')
done

curl -s -X POST "$NDI_BASE_URL/v1/workspaces/$WS/automatic-search" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What were total liabilities at year end?", "mode": "fact"}'

client.upload_and_ingest(...) collapses the upload and ingest calls for a single file. From the terminal, ndi files upload ./corpus --ingest walks a local folder, skips unsupported types, and queues ingestion — see NDI CLI.

Creation options

Field	Default	Meaning
`name`	you must set this	Human-readable identifier
`domain_slug`	`generic`	Taxonomy vocabulary
`access.labels`	`[]`	Frozen `{name, description}` objects from the catalog
`access.default_label`	none	Applied when a file is uploaded without a classified label
`knowledge_graph.auto_build`	`false`	Chain a graph build after every ingestion
`ledger_understanding.trigger`	`auto`	Chain a ledger-understanding run after ingestion that landed a journal-line table (`always` / `off` change that)
`ledger_understanding.gl_parsing`	`true`	Map journals to balanced sub-journals when the stage runs
`retention_policy`	server defaults	Derived / source / job TTLs

See Access labels for the catalog and the workspace allowed set. ledger_understanding is a whole-block PATCH, like knowledge-graph: send the complete new policy. off stops ingestion from chaining a run and never refuses start_ledger_understanding.

List, stats, delete

from ndi_sdk import NdiClient

with NdiClient() as client:
    for workspace in client.workspaces.iter_all(name_contains="audit"):
        print(workspace.workspace_id, workspace.name)
        print(client.workspaces.stats(workspace.workspace_id))

Delete requires confirm_name matching the workspace name. It returns a workspace_delete job and cannot be undone.

Next