Skip to main content
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:
The name is immutable after creation. 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:
A file’s labels must be a subset of the workspace’s allowed labels. This set is immutable: changing it requires a new workspace. default_label is applied to files uploaded without an explicit label.

​
File-level labels

When you upload a file into a workspace, assign labels from the allowed set via the metadata JSON form field:

​
Coverage reporting

Every tool and query response includes coverage — how many candidates were withheld by the access predicate and which labels would unlock them:
  • 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. Labels use AND logic: a file is visible only if all of the key’s required visibility labels are present on the file.

​
Label catalog management

List labels:
Update description:
Delete (only if not referenced by any workspace):

​
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:
  1. After a document file is parsed and split into logical documents, a classification step reads each document’s markdown content.
  2. 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.
  3. 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.