Workspaces

A workspace is a named collection of files and derived outputs, pinned to a domain (vocabulary for classification) and a set of access labels.

Workspace properties

When you create a workspace, you choose:

Name — human-readable identifier.
Domain — vocabulary for classification (domain_slug, e.g. "generic"). The domain determines the taxonomy labels available for document classification.
Access labels — a frozen subset of your organization’s label catalog (see Access labels).

Creating a workspace

List available domains first to get the correct domain_slug:

Python
TypeScript
cURL

from ndi_sdk import NdiClient
from ndi_sdk.models.common import AccessConfig, AccessLabel

with NdiClient() as client:
    domains = client.domains.list()
    workspace = client.workspaces.create(
        name="q4-2025-audit",
        domain_slug="generic",
        access=AccessConfig(
            labels=[
                AccessLabel(
                    name="financial",
                    description="Financial documents.",
                ),
                AccessLabel(
                    name="audit_only",
                    description="Restricted to the audit team.",
                ),
            ],
            default_label="financial",
        ),
    )

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const domains = await client.domains.list();
const workspace = await client.workspaces.create({
  name: "q4-2025-audit",
  domain_slug: "generic",
  access: {
    labels: [
      { name: "financial", description: "Financial documents." },
      { name: "audit_only", description: "Restricted to the audit team." },
    ],
    default_label: "financial",
  },
});

curl "$NDI_BASE_URL/v1/domains" \
  -H "X-API-Key: $NDI_API_KEY"

curl -X POST "$NDI_BASE_URL/v1/workspaces" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "q4-2025-audit",
    "domain_slug": "generic",
    "access": {
      "labels": [
        {"name": "financial", "description": "Financial documents."},
        {"name": "audit_only", "description": "Restricted to the audit team."}
      ],
      "default_label": "financial"
    }
  }'

Response:

{
  "workspace_id": "550e8400-e29b-41d4-a716-446655440001",
  "name": "q4-2025-audit",
  "domain_slug": "generic",
  "domain_version": 3,
  "knowledge_graph": {"auto_build": false},
  "ledger_understanding": {"trigger": "auto", "gl_parsing": true},
  "created_at": "2026-08-09T12:00:00Z"
}

Workspace stats

Python
TypeScript
cURL

stats = client.workspaces.stats(workspace_id)

const workspaceId = "550e8400-e29b-41d4-a716-446655440001";
const stats = await client.workspaces.stats(workspaceId);

curl "$NDI_BASE_URL/v1/workspaces/$WS/stats" \
  -H "X-API-Key: $NDI_API_KEY"

Returns file counts, ingestion status distribution, storage bytes, and knowledge-graph build status.

Listing workspaces

Python
TypeScript
cURL

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

for await (const workspace of client.workspaces.iterAll({ name_contains: "audit" })) {
  console.log(workspace.workspace_id, workspace.name);
}

curl "$NDI_BASE_URL/v1/workspaces" \
  -H "X-API-Key: $NDI_API_KEY"

Returns a keyset-paginated page. Pass ?cursor=<next_cursor> for subsequent pages.

Deleting a workspace

Python
TypeScript
cURL

queued = client.workspaces.delete(
    workspace_id,
    confirm_name="q4-2025-audit",
)

const workspaceId = "550e8400-e29b-41d4-a716-446655440001";
const queued = await client.workspaces.delete(workspaceId, {
  confirm_name: "q4-2025-audit",
});

curl -X DELETE "$NDI_BASE_URL/v1/workspaces/$WS" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirm_name": "q4-2025-audit"}'

confirm_name must exactly match the workspace’s name. This is a cascade: all files, derivatives, and ingestion metadata are deleted. It cannot be undone. The response is a Job with kind: "workspace_delete".

Knowledge graph

A graph is built when you ask for one. It is billable and runs for as long as the corpus takes, so ingesting files never commits you to one:

Python
TypeScript
cURL

queued = client.ingestion.build_knowledge_graph(workspace_id)
job = client.jobs.wait(queued.job_id, timeout=600)

const workspaceId = "550e8400-e29b-41d4-a716-446655440001";
const queued = await client.ingestion.buildKnowledgeGraph(workspaceId);
const job = await client.jobs.wait(queued.job_id, { timeout: 600 });

curl -X POST "$NDI_BASE_URL/v1/workspaces/$WS/knowledge-graph/builds" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

For a workspace that should always hold a graph over everything it ingests, turn auto_build on and every ingestion will chain one. PATCH replaces the knowledge_graph block whole, so if the workspace already has exclude_path_prefixes or exclude_categories set, read the current block first and send it back with auto_build changed — sending auto_build alone resets the rest of the block to its schema defaults (empty), silently dropping any exclusion rules:

Python
TypeScript
cURL

from ndi_sdk.models.workspaces import KnowledgeGraphConfig

workspace = client.workspaces.get(workspace_id)
updated = client.workspaces.update(
    workspace_id,
    knowledge_graph=KnowledgeGraphConfig(
        auto_build=True,
        exclude_path_prefixes=workspace.knowledge_graph.exclude_path_prefixes,
        exclude_categories=workspace.knowledge_graph.exclude_categories,
    ),
)

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 ?? [],
  },
});

curl "$NDI_BASE_URL/v1/workspaces/$WS" \
  -H "X-API-Key: $NDI_API_KEY"
# => {"knowledge_graph": {"auto_build": false, "exclude_path_prefixes": ["drafts/"], "exclude_categories": []}, ...}

curl -X PATCH "$NDI_BASE_URL/v1/workspaces/$WS" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"knowledge_graph": {"auto_build": true, "exclude_path_prefixes": ["drafts/"], "exclude_categories": []}}'

The same whole-block rule applies to ledger_understanding (trigger, gl_parsing). auto (the default) chains a run after ingestion only when the workspace already holds a journal-line table; off stops chaining and never refuses an explicit start. See Ledger understanding. See Knowledge graph and the workspace guide.

Global context

global_context is background text that every query in the workspace should know, such as how the journals are keyed or which entity the ledger covers. Save it once, and every je-testing or search request that omits context runs with it. Send context to replace it for one run, or "context": "" to run with none. It is capped at the same length as a query’s context.

Python
TypeScript
cURL

updated = client.workspaces.update(
    workspace_id,
    global_context="Journal ID = period + subperiod + Journal Cd + posting sequence number",
)

const workspaceId = "550e8400-e29b-41d4-a716-446655440001";
const updated = await client.workspaces.update(workspaceId, {
  global_context: "Journal ID = period + subperiod + Journal Cd + posting sequence number",
});

curl -X PATCH "$NDI_BASE_URL/v1/workspaces/$WS" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"global_context": "Journal ID = period + subperiod + Journal Cd + posting sequence number"}'

Send "global_context": "" to clear it.

Getting started

Guides

Agents

Concepts

Troubleshooting

Workspace properties

Creating a workspace

Workspace stats

Listing workspaces

Deleting a workspace

Knowledge graph

Global context

​Workspace properties

​Creating a workspace

​Workspace stats

​Listing workspaces

​Deleting a workspace

​Knowledge graph

​Global context

Workspace properties

Creating a workspace

Workspace stats

Listing workspaces

Deleting a workspace

Knowledge graph

Global context