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 and the knowledge-graph ontology.
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:

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

Then create:

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": ["financial", "audit-only"],
      "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},
  "created_at": "2026-08-09T12:00:00Z"
}

Workspace stats

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

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

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:

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:

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": []}}'

See Knowledge graph.

Getting started

SDKs and agents

Concepts

Workspace properties

Creating a workspace

Workspace stats

Listing workspaces

Deleting a workspace

Knowledge graph

​Workspace properties

​Creating a workspace

​Workspace stats

​Listing workspaces

​Deleting a workspace

​Knowledge graph

Workspace properties

Creating a workspace

Workspace stats

Listing workspaces

Deleting a workspace

Knowledge graph