# Labels

> Organization-wide Labels for Forms, Automations, and Check-ins — entitlement (feature enabled, non-guest), CRUD, assign, filter, and LabelSummary shape.

Language: en
Canonical: https://www.dailybot.com/developers/api/labels
Markdown: send header `Accept: text/markdown` on any URL to receive Markdown instead of HTML.
Last Updated: 2026-08-03

---

## Organization Labels

Dailybot Labels are a shared, org-wide taxonomy you attach to **Forms**, **Automations** (workflows), and **Check-ins**. They power filtering in list endpoints, the Settings Labels manager, and the associated-items modal. Labels require the Labels feature to be enabled for the organization; guest users are denied on every Labels endpoint.

Product overview: [/hc/account/organization/labels/](/hc/account/organization/labels/).

> **CLI & Agent Skill:** Use `dailybot label …` or the `dailybot-labels` sub-skill (`dailybot-cli >= 3.9.0`). See [/developers/cli](/developers/cli) and [/developers/agent-skill](/developers/agent-skill).

### Entitlement

Call `GET /v1/labels/entitlement/` before building Labels UI. The response always returns flags (never gates itself):

| Field | Meaning |
|-------|---------|
| `entitled` | Labels feature is enabled for the organization **and** the caller is not a guest |
| `is_guest` | Caller is a guest (always denied) |
| `can_create` | Caller may create labels |
| `can_manage_all` | Elevated manage-all (admins) |
| `can_hard_delete` | Elevated hard-delete (org-level entitlement flag; distinct from per-label `permissions.can_delete` on Label objects) |

When the feature is off, callers receive `entitled: false` with `reason: feature_not_enabled`. Guests receive `entitled: false` with `reason: guest_not_allowed`.

### LabelSummary shape

Compact label rows on entity **list** endpoints, **Forms detail**, and assign responses use **LabelSummary**:

```json
{
  "uuid": "label-uuid",
  "name": "Release",
  "color": "#4F46E5",
  "is_archived": false
}
```

Full Label objects from `/v1/labels/` also expose `usage: {forms, automations, checkins, total}`, `permissions`, and audit fields.

### Assign labels to entities

Assign endpoints use **POST** (not PUT):

| Domain | Replace-set on one entity | Batch |
|--------|---------------------------|-------|
| Forms | `POST /v1/forms/{uuid}/labels/` | `POST /v1/forms/labels/batch/` |
| Check-ins | `POST /v1/checkins/{uuid}/labels/` | `POST /v1/checkins/labels/batch/` |
| Automations | `POST /v1/workflows/{uuid}/labels/` | `POST /v1/workflows/labels/batch/` |

Replace-set body: `{"label_uuids": ["…", "…"]}`. Batch body: `{"entity_uuids": ["…"], "label_uuids": ["…"], "mode": "add"|"remove"|"replace"}`.

### Filter list endpoints

Forms, check-ins, and automations list endpoints accept:

| Param | Notes |
|-------|-------|
| `labels` | Comma-separated Label UUIDs (max 50). **Match-any (OR within the comma-separated set)** — the entity must have at least one of the selected labels. Requires Labels entitlement (feature enabled). |
| `featured` | `true` / `false` — filter by the caller's **private** Featured state (not Labels-gated). |
| `prioritize_featured` | `true` — Featured rows first. On **Forms**, `order` / `is_ascend` apply as secondary sort (check-ins and automations lists do not document those params). |

When list enrichment is temporarily unavailable, enrichment params return `503` with `dashboard_enrichment_temporarily_unavailable`. See [/developers/errors](/developers/errors) for general retry guidance.

### Common error codes

| Code | HTTP | When |
|------|------|------|
| `feature_not_available` | 403 | Labels feature not enabled |
| `guest_not_allowed` | 403 | Guest caller |
| `permission_denied` | 403 | Insufficient role on label or entity |
| `duplicate_name` | 409 | Label name collision |
| `archived_label` | 400 | Assigning an archived label |
| `label_limit_exceeded` | 400 | Assign/batch would exceed the per-entity Label attachment limit |
| `invalid_color` | 400 | Create/PATCH color is not valid hex |
| `label_in_use` | 409 | Hard-delete while attached |
| `not_found` | 404 | Unknown label or entity |

### Related docs

- [Forms — Labels & Featured](/developers/api/forms#labels-and-featured)
- [Check-ins](/developers/api/check-ins)
- [Automations](/developers/api/workflows)
- [Users — Personalization](/developers/api/users#personalization)

## Endpoints in this group

Organization-wide taxonomy for Forms, Automations, and Check-ins. Requires Labels entitlement (feature enabled). CRUD in Settings, assign to entities, filter list endpoints. Guests are denied.

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/v1/labels/entitlement/` | Labels entitlement |
| GET | `/v1/labels/` | List organization labels |
| POST | `/v1/labels/` | Create a label |
| GET | `/v1/labels/{label_uuid}/` | Retrieve a label |
| PATCH | `/v1/labels/{label_uuid}/` | Update a label |
| DELETE | `/v1/labels/{label_uuid}/` | Hard-delete a label |
| POST | `/v1/labels/{label_uuid}/archive/` | Archive a label |
| GET | `/v1/labels/{label_uuid}/items/` | List items with a label |

### GET `/v1/labels/entitlement/`

**Labels entitlement**

Returns whether the caller is entitled to Labels (feature enabled for the organization and caller is not a guest). Always returns entitlement flags — never gates the response itself. Feature-off and guest users receive entitled=false with reason codes.

- **Auth:** API key (`X-API-KEY`), CLI Bearer (read)
- **Rate limit:** `default`
- **Pagination:** No pagination

#### Response body

```json
{
  "entitled": "boolean",
  "feature": "string",
  "reason": "string | null (feature_not_enabled | guest_not_allowed | organization_required)",
  "is_guest": "boolean",
  "can_create": "boolean",
  "can_manage_all": "boolean",
  "can_hard_delete": "boolean",
  "can_manage": "boolean (same as can_create when entitled)"
}
```

#### Error codes

| Status | When |
|--------|------|
| `401` | Missing/invalid/expired credential |
| `429` | Throttled — Retry-After header set |

#### Example (curl)

```bash
curl -sS 'https://api.dailybot.com/v1/labels/entitlement/' \
  -H 'X-API-KEY: $DAILYBOT_API_KEY'
```

#### Notes

- Call this before building Labels UI or assign flows. Guests always receive is_guest=true and entitled=false.

### GET `/v1/labels/`

**List organization labels**

Paginated list of organization Labels for Settings and pickers. Requires Labels entitlement (feature enabled). Each row includes canonical usage: {forms, automations, checkins, total}.

- **Auth:** API key (`X-API-KEY`), CLI Bearer (read)
- **Rate limit:** `default`
- **Pagination:** Limit-offset pagination

#### Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `search` | string | No | Case-insensitive substring on label name. |
| `owner_user_ids` | string (CSV) | No | Filter by creator UUIDs (max 50). |
| `is_archived` | boolean | No | When true, list archived labels. Default false. |
| `order` | string | No | Sort field: name, usage, last_applied_at, created_at. Default name. |
| `is_ascend` | boolean | No | Sort direction. Default ascending for name. |
| `limit` | integer | No | Page size. Default 20, min 1, max 100. |
| `offset` | integer | No | Pagination offset. Default 0. |

#### Response body

```json
{
  "count": "integer",
  "next": "string | null",
  "previous": "string | null",
  "results": "array<Label>"
}
```

#### Error codes

| Status | When |
|--------|------|
| `401` | Missing/invalid/expired credential |
| `403` | feature_not_available, permission_denied, guest_not_allowed |
| `429` | Throttled — Retry-After header set |

#### Example (curl)

```bash
curl -sS 'https://api.dailybot.com/v1/labels/?order=usage&is_ascend=false&limit=50' \
  -H 'X-API-KEY: $DAILYBOT_API_KEY'
```

### POST `/v1/labels/`

**Create a label**

Creates an organization Label. Requires Labels entitlement (feature enabled) and can_create permission. Label names are case-insensitive unique per organization.

- **Auth:** API key (`X-API-KEY`), CLI Bearer (write)
- **Rate limit:** `default`
- **Pagination:** No pagination

#### Request body

```json
{
  "name": "string (required)",
  "color": "string (hex, optional, default system color)",
  "description": "string | null (optional)"
}
```

#### Response body

```json
{
  "uuid": "string",
  "name": "string",
  "color": "string",
  "description": "string | null",
  "is_archived": "boolean",
  "usage": "{forms, automations, checkins, total}",
  "permissions": "{can_edit, can_archive, can_delete}"
}
```

#### Error codes

| Status | When |
|--------|------|
| `400` | validation_error, invalid_color |
| `401` | Missing/invalid/expired credential |
| `403` | feature_not_available, permission_denied, guest_not_allowed |
| `409` | duplicate_name — a label with this name already exists |
| `429` | Throttled — Retry-After header set |

#### Example (curl)

```bash
curl -sS -X POST 'https://api.dailybot.com/v1/labels/' \
  -H 'X-API-KEY: $DAILYBOT_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Release", "color": "#4F46E5"}'
```

### GET `/v1/labels/{label_uuid}/`

**Retrieve a label**

Retrieve one organization Label by UUID, including usage counts and per-caller permissions.

- **Auth:** API key (`X-API-KEY`), CLI Bearer (read)
- **Rate limit:** `default`
- **Pagination:** No pagination

#### Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `label_uuid` | string (uuid) | Yes | — |

#### Response body

```json
{
  "uuid": "string",
  "name": "string",
  "color": "string",
  "description": "string | null",
  "is_archived": "boolean",
  "usage": "{forms, automations, checkins, total}",
  "created_by": "object | null",
  "last_applied_at": "string (ISO 8601) | null",
  "permissions": "{can_edit, can_archive, can_delete}"
}
```

#### Error codes

| Status | When |
|--------|------|
| `401` | Missing/invalid/expired credential |
| `403` | feature_not_available, permission_denied, guest_not_allowed |
| `404` | not_found — label not in caller's organization |
| `429` | Throttled — Retry-After header set |

#### Example (curl)

```bash
curl -sS 'https://api.dailybot.com/v1/labels/{label_uuid}/' \
  -H 'X-API-KEY: $DAILYBOT_API_KEY'
```

#### Notes

- permissions.can_delete is per-label (caller may hard-delete this Label). Distinct from GET /v1/labels/entitlement/ can_hard_delete, which is the org-level elevated hard-delete flag.

### PATCH `/v1/labels/{label_uuid}/`

**Update a label**

Partial update of a Label (name, color, description, is_archived). Requires can_edit on the label.

- **Auth:** API key (`X-API-KEY`), CLI Bearer (write)
- **Rate limit:** `default`
- **Pagination:** No pagination

#### Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `label_uuid` | string (uuid) | Yes | — |

#### Request body

```json
{
  "name": "string (optional)",
  "color": "string (optional hex)",
  "description": "string | null (optional)",
  "is_archived": "boolean (optional)"
}
```

#### Response body

```json
{
  "uuid": "string",
  "name": "string",
  "color": "string",
  "is_archived": "boolean",
  "usage": "{forms, automations, checkins, total}"
}
```

#### Error codes

| Status | When |
|--------|------|
| `400` | validation_error, invalid_color |
| `401` | Missing/invalid/expired credential |
| `403` | permission_denied |
| `404` | not_found |
| `409` | duplicate_name |
| `429` | Throttled — Retry-After header set |

#### Example (curl)

```bash
curl -sS -X PATCH 'https://api.dailybot.com/v1/labels/{label_uuid}/' \
  -H 'X-API-KEY: $DAILYBOT_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"color": "#059669"}'
```

### DELETE `/v1/labels/{label_uuid}/`

**Hard-delete a label**

Permanently deletes a Label. Elevated role required (can_hard_delete). Returns 409 when the label is still attached to items — archive or detach first.

- **Auth:** API key (`X-API-KEY`), CLI Bearer (write)
- **Rate limit:** `default`
- **Pagination:** No pagination

#### Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `label_uuid` | string (uuid) | Yes | — |

#### Error codes

| Status | When |
|--------|------|
| `401` | Missing/invalid/expired credential |
| `403` | permission_denied |
| `404` | not_found |
| `409` | label_in_use — label is attached to one or more items |
| `429` | Throttled — Retry-After header set |

#### Example (curl)

```bash
curl -sS -X DELETE 'https://api.dailybot.com/v1/labels/{label_uuid}/' \
  -H 'X-API-KEY: $DAILYBOT_API_KEY'
```

### POST `/v1/labels/{label_uuid}/archive/`

**Archive a label**

Archives a Label (sets is_archived=true). Idempotent. Archived labels cannot be newly assigned but may remain on existing items.

- **Auth:** API key (`X-API-KEY`), CLI Bearer (write)
- **Rate limit:** `default`
- **Pagination:** No pagination

#### Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `label_uuid` | string (uuid) | Yes | — |

#### Response body

```json
{
  "uuid": "string",
  "name": "string",
  "is_archived": "true"
}
```

#### Error codes

| Status | When |
|--------|------|
| `401` | Missing/invalid/expired credential |
| `403` | permission_denied |
| `404` | not_found |
| `429` | Throttled — Retry-After header set |

#### Example (curl)

```bash
curl -sS -X POST 'https://api.dailybot.com/v1/labels/{label_uuid}/archive/' \
  -H 'X-API-KEY: $DAILYBOT_API_KEY'
```

#### Notes

- Use PATCH with is_archived=false on the label detail endpoint to restore an archived label.

### GET `/v1/labels/{label_uuid}/items/`

**List items with a label**

Paginated list of Forms, Automations, and Check-ins associated with a Label. Visibility-aware — only items the caller can see are returned (powers the associated-items modal in Settings).

- **Auth:** API key (`X-API-KEY`), CLI Bearer (read)
- **Rate limit:** `default`
- **Pagination:** Limit-offset pagination

#### Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `label_uuid` | string (uuid) | Yes | — |

#### Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `type` | string | No | Filter by item type: forms, automations, checkins. |
| `search` | string | No | Case-insensitive search on item name. |
| `limit` | integer | No | Page size. Default 20, max 100. |
| `offset` | integer | No | Pagination offset. |

#### Response body

```json
{
  "count": "integer",
  "next": "string | null",
  "previous": "string | null",
  "results": "array<{type, uuid, name, active, archived, assigned_at}>"
}
```

#### Error codes

| Status | When |
|--------|------|
| `401` | Missing/invalid/expired credential |
| `403` | feature_not_available, permission_denied |
| `404` | not_found |
| `429` | Throttled — Retry-After header set |

#### Example (curl)

```bash
curl -sS 'https://api.dailybot.com/v1/labels/{label_uuid}/items/?type=forms' \
  -H 'X-API-KEY: $DAILYBOT_API_KEY'
```

---

## Developer portal navigation

**Getting Started**

- [Overview](/developers)
- [Quick start](/developers/getting-started)
- [Authentication](/developers/authentication)

**API Reference**

- [API Overview](/developers/api)
- [Users](/developers/api/users)
- [Organization](/developers/api/organization)
- [Teams](/developers/api/teams)
- [Invitations](/developers/api/invitations)
- [Check-ins](/developers/api/check-ins)
- [Forms](/developers/api/forms)
- [Labels](/developers/api/labels) (this page)
- [Report channels](/developers/api/report-channels)
- [Templates](/developers/api/templates)
- [Kudos](/developers/api/kudos)
- [Mood tracking](/developers/api/mood)
- [Important dates](/developers/api/important-dates)
- [Messaging](/developers/api/messaging)
- [Automations](/developers/api/workflows)
- [Webhooks](/developers/api/webhooks)
- [Commands platform](/developers/api/commands-platform)
- [Agents](/developers/api/agents)
- [OAuth2](/developers/api/oauth2)
- [Integrations](/developers/api/integrations)
- [CLI](/developers/api/cli)

**API guides**

- [Errors & Status Codes](/developers/errors)
- [Rate Limits](/developers/rate-limits)
- [Conventions](/developers/conventions)
- [API Changelog](/developers/api-changelog)
- [Recipes](/developers/recipes)

**Developer Features**

- [Custom commands](/developers/custom-commands)
- [Serverless commands](/developers/serverless)
- [Webhooks & events](/developers/webhooks)
- [Automation API trigger](/developers/workflow-trigger)
- [Activity API](/developers/activity-api)

**CLI**

- [Overview](/developers/cli)
- [Authentication](/developers/cli-authentication)
- [Command reference](/developers/cli-reference)
- [CI/CD recipes](/developers/cli-ci-cd)
- [Configuration](/developers/cli-configuration)
- [Troubleshooting](/developers/cli-troubleshooting)

**Agent Skill**

- [Overview](/developers/agent-skill)
- [Skills catalog](/skills)

---

## Site navigation

**Product:**
- [Home](/)
- [Product](/product)
- [Pricing](/pricing)
- [Enterprise](/enterprise)
- [Integrations](/integrations)
- [Templates](/templates)

**Resources:**
- [Blog](/blog)
- [Academy](/academy)
- [Changelog](/changelog)
- [Help Center](/help)
- [Developers](/developers)
- [Agents](/agents)

**Company:**
- [About](/about)
- [Careers](/careers)
- [Security](/security)
- [Contact Sales](/demo)

**Connect:**
- [LinkedIn](https://www.linkedin.com/company/dailybot/)
- [X/Twitter](https://twitter.com/dailybot)
- [GitHub](https://github.com/Dailybot-Inc)
- [YouTube](https://www.youtube.com/channel/UC3uM9V52vwX7e3vQpCc4qvA)