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

> Tenant label catalog — 5 endpoints

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

```json theme={"dark"}
{
  "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:**

```json theme={"dark"}
{
  "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):**

```json theme={"dark"}
{
  "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:**

```json theme={"dark"}
{
  "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

```bash theme={"dark"}
# 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](/concepts/access-labels) for the full access-control model.