Access labels

Access labels are your organization’s vocabulary for controlling file visibility within workspaces. Build a reusable catalog, then freeze a subset into each workspace at creation time. All list routes use keyset cursor pagination (cursor / next_cursor).

List access labels

GET /v1/access-labels

Page through the tenant’s label catalog. Query parameters:

cursor (optional) — Opaque cursor from a previous page’s next_cursor.
limit (optional, default 50, max 200) — Rows per page.

Response:

{
  "items": [
    {
      "access_label_id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "financial",
      "description": "Financial documents and extracts",
      "created_at": "2026-01-15T09:00:00Z",
      "updated_at": "2026-01-15T09:00:00Z"
    }
  ],
  "next_cursor": null,
  "total_count": 1
}

Response fields:

access_label_id — UUID for this catalog entry.
name — Slug pattern ([a-z0-9]+(?:_[a-z0-9]+)*, max 64 chars). Immutable after creation.
description — Used as the classifier’s prompt when assigning labels during ingestion.

Create access label

POST /v1/access-labels

Add a label to the tenant catalog. Request:

{
  "name": "financial",
  "description": "Financial documents: balance sheets, income statements, and audit schedules."
}

Body fields:

name (required) — Slug pattern, max 64 chars. Must be unique in the tenant catalog.
description (required, max 2000 chars) — Write for the classifier — this string IS the classification prompt.

Response (201 Created):

{
  "access_label_id": "550e8400-e29b-41d4-a716-446655440001",
  "name": "financial",
  "description": "Financial documents: balance sheets, income statements, and audit schedules.",
  "created_at": "2026-01-15T09:00:00Z",
  "updated_at": "2026-01-15T09:00:00Z"
}

Errors:

access_label_name_taken (409) — A label with this name already exists in the tenant catalog.

Get access label

GET /v1/access-labels/{access_label_id}

Retrieve one catalog label. Response: Same shape as a Create response.

Update access label

PATCH /v1/access-labels/{access_label_id}

Update a label’s description. Name changes are refused — rename by deleting and creating. Request:

{
  "description": "Financial documents including quarterly filings and audit schedules."
}

Body fields:

description (optional, max 2000 chars) — Updated classifier prompt.

Response (200): Same shape as Create.

Delete access label

DELETE /v1/access-labels/{access_label_id}

Remove a label from the catalog. Response: 204 No Content Errors:

access_label_not_found (404) — Label does not exist.
access_label_in_use (409) — Label is still referenced by a workspace, a grant, or a file.

Workflow

# 1. Create labels in the tenant catalog
curl -X POST "$NDI_BASE_URL/v1/access-labels" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "financial", "description": "Financial documents..."}'

# 2. Freeze a subset when creating a workspace
curl -X POST "$NDI_BASE_URL/v1/workspaces" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "q4-audit",
    "access": {
      "labels": [{"name": "financial", "description": "Financial documents..."}],
      "default_label": "financial"
    }
  }'

See Access labels and coverage for the full access-control model.

Granular operations

Platform resources

Knowledge graph

Tools

Operations

List access labels

Create access label

Get access label

Update access label

Delete access label

Workflow

​List access labels

​Create access label

​Get access label

​Update access label

​Delete access label

​Workflow

List access labels

Create access label

Get access label

Update access label

Delete access label

Workflow