Access labels

Access labels are visibility tags, not roles. Create them in the organization catalog first. A workspace freezes a subset as {name, description} objects. description is the classifier prompt used at ingestion. Hyphens are illegal in names — use audit_only, not audit-only.

Python
TypeScript
curl

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

with NdiClient() as client:
    client.domains.create_access_label(
        name="financial",
        description="Financial statements, invoices, and extracts.",
    )
    client.domains.create_access_label(
        name="audit_only",
        description="Restricted to the audit team.",
    )
    workspace = client.workspaces.create(
        name="q4-audit",
        access=AccessConfig(
            labels=[
                AccessLabel(name="financial", description="Financial statements, invoices, and extracts."),
                AccessLabel(name="audit_only", description="Restricted to the audit team."),
            ],
            default_label="financial",
        ),
    )
    print(workspace.workspace_id)

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
await client.domains.createAccessLabel({
  name: "financial",
  description: "Financial statements, invoices, and extracts.",
});
await client.domains.createAccessLabel({
  name: "audit_only",
  description: "Restricted to the audit team.",
});
const workspace = await client.workspaces.create({
  name: "q4-audit",
  access: {
    labels: [
      { name: "financial", description: "Financial statements, invoices, and extracts." },
      { name: "audit_only", description: "Restricted to the audit team." },
    ],
    default_label: "financial",
  },
});
console.log(workspace.workspace_id);

curl -s -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 statements, invoices, and extracts."}'

curl -s -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 statements, invoices, and extracts."},
        {"name": "audit_only", "description": "Restricted to the audit team."}
      ],
      "default_label": "financial"
    }
  }'

File visibility

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 using each label’s description as the prompt. A document that matches none gets null (visible to everyone) or falls back to default_label if classification fails. The allowed set is immutable. Changing it requires a new workspace.

Coverage

Tool and search responses include coverage when your key cannot see every candidate:

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

A file carries one visibility label. It is visible when that label is in your key’s granted set, or when the file has no label. A direct read of a source whose documents carry several distinct labels requires your key to hold all of them. See Access labels concept.

Getting started

Guides

Concepts

Python SDK

TypeScript SDK

Agents

Troubleshooting

File visibility

Coverage

​File visibility

​Coverage

File visibility

Coverage