Access labels and coverage

Access labels are your organization’s vocabulary for controlling file visibility within workspaces. They are metadata tags — not roles or permissions — that gate which files a query or tool can see.

Organizing labels

Create labels in your organization’s catalog:

Python
TypeScript
cURL

from ndi_sdk import NdiClient

with NdiClient() as client:
    label = client.domains.create_access_label(
        name="financial",
        description="Financial documents and extracts",
    )

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const label = await client.domains.createAccessLabel({
  name: "financial",
  description: "Financial documents and extracts",
});

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 and extracts"
  }'

The name is immutable after creation and must match ^[a-z0-9]+(?:_[a-z0-9]+)*$ (underscores, no hyphens — audit_only). The PATCH endpoint updates only description. Labels in the catalog are reusable: multiple workspaces can include the same label.

Workspace-level labels

When you create a workspace, you freeze a subset of your organization’s label catalog as the workspace’s allowed set:

Python
TypeScript
cURL

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

with NdiClient() as client:
    workspace = client.workspaces.create(
        name="q4-audit",
        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 workspace = await client.workspaces.create({
  name: "q4-audit",
  access: {
    labels: [
      { name: "financial", description: "Financial documents." },
      { name: "audit_only", description: "Restricted to the audit team." },
    ],
    default_label: "financial",
  },
});

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

Each workspace label is {name, description} — description is the classifier prompt. Create matching catalog entries when you want a shared vocabulary; create does not require the name to already exist in the catalog. A file’s labels must be a subset of this allowed set. The set is immutable: changing it requires a new workspace. default_label is applied to files uploaded without an explicit label.

File-level labels

Upload metadata.labels is caller-supplied key-value metadata ({"year":"2025"}), not the access catalog. Visibility labels are assigned at ingestion from the workspace’s frozen set (see below). A file’s labels must be a subset of that allowed set.

Coverage reporting

Every tool and query response includes coverage — how many candidates were withheld by the access predicate and which labels would unlock them:

{
  "coverage": {
    "restricted_candidates": 12,
    "labels_required": ["audit_only"]
  },
  "hits": [...]
}

restricted_candidates — Files visible in scope but withheld by your key’s access predicate.
labels_required — Labels your key would need to see the withheld files.

This transparency prevents silent data loss: you know when restricted files exist even if you cannot read them.

Your key’s scope

An API key’s access predicate is set when the key is created. When you call a tool in a workspace, the API filters results to files visible to your key and returns coverage describing what was withheld. A file carries one visibility label and is visible when that label is in the key’s granted set (or when the file has no label). Reading a source whose documents carry several distinct labels requires the key to hold all of them.

Label catalog management

Python
TypeScript
cURL

labels = client.domains.list_access_labels()
updated = client.domains.update_access_label(
    access_label_id,
    description="Updated description",
)
client.domains.delete_access_label(access_label_id)

const accessLabelId = "550e8400-e29b-41d4-a716-446655440002";
const labels = await client.domains.listAccessLabels();
const updated = await client.domains.updateAccessLabel(accessLabelId, {
  description: "Updated description",
});
await client.domains.deleteAccessLabel(accessLabelId);

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

curl -X PATCH "$NDI_BASE_URL/v1/access-labels/$LABEL_ID" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated description"}'

curl -X DELETE "$NDI_BASE_URL/v1/access-labels/$LABEL_ID" \
  -H "X-API-Key: $NDI_API_KEY"

Deletion succeeds only when no workspace references the label.

Automatic classification at ingestion

When a workspace declares labels, NDI automatically classifies each logical document produced during ingestion using the label descriptions as prompts. How it works:

After a document file is parsed and split into logical documents, a classification step reads each document’s markdown content.
An LLM call compares the content against your label descriptions and assigns the best matching label — or marks the document as intentionally unlabelled (null label, visible to everyone) when no label fits.
If classification fails for any reason, the document falls back to default_label so ingestion always completes.

Mixed-label sources: A single uploaded file can split into logical documents with different labels (e.g. a board packet whose first section is public and whose appendix is privileged). Reading the source file directly requires holding every label present on any of its logical documents. Label descriptions matter: The description you write for each label is the classifier’s prompt. Clear, specific descriptions produce better assignments. Skipped for unfiltered workspaces: If a workspace declares no labels, no classification pass runs and every file is visible to all callers.

Getting started

Guides

Agents

Concepts

Troubleshooting

Organizing labels

Workspace-level labels

File-level labels

Coverage reporting

Your key’s scope

Label catalog management

Automatic classification at ingestion

​Organizing labels

​Workspace-level labels

​File-level labels

​Coverage reporting

​Your key’s scope

​Label catalog management

​Automatic classification at ingestion

Organizing labels

Workspace-level labels

File-level labels

Coverage reporting

Your key’s scope

Label catalog management

Automatic classification at ingestion