> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ndi.nace.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces

> Persistent storage, configuration, and access control

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](/concepts/access-labels)).

***

## Creating a workspace

List available domains first to get the correct `domain_slug`:

```bash theme={"dark"}
curl "$NDI_BASE_URL/v1/domains" \
  -H "X-API-Key: $NDI_API_KEY"
```

Then create:

```bash theme={"dark"}
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:

```json theme={"dark"}
{
  "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

```bash theme={"dark"}
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

```bash theme={"dark"}
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

```bash theme={"dark"}
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:

```bash theme={"dark"}
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:

```bash theme={"dark"}
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](/api-reference/knowledge-graph).