> ## 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.

# Access labels

> Catalog labels, freeze them on a workspace, and debug coverage

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`.

<Tabs>
  <Tab title="Python">
    ```python theme={"dark"}
    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)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={"dark"}
    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);
    ```
  </Tab>

  <Tab title="curl">
    ```bash theme={"dark"}
    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"
        }
      }'
    ```
  </Tab>
</Tabs>

## 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:

```json theme={"dark"}
{
  "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](/concepts/access-labels).