Skip to content
view raw .md

Labels

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.

On this page
GET/v1/labels/entitlement/API keyCLI Auth

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.

Response

{
  "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)"
}

Errors

StatusWhen
401Missing/invalid/expired credential
429Throttled — Retry-After header set
curl -sS 'https://api.dailybot.com/v1/labels/entitlement/' \
  -H 'X-API-KEY: $DAILYBOT_API_KEY'

Try it

This is a copy-only helper — the request is not sent from your browser. Paste the command into your terminal to execute it.

  • Call this before building Labels UI or assign flows. Guests always receive is_guest=true and entitled=false.
GET/v1/labels/API keyCLI AuthLimit-offset pagination

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

Query parameters

NameTypeRequiredDescription
searchstringOptionalCase-insensitive substring on label name.
owner_user_idsstring (CSV)OptionalFilter by creator UUIDs (max 50).
is_archivedbooleanOptionalWhen true, list archived labels. Default false.
orderstringOptionalSort field: name, usage, last_applied_at, created_at. Default name.
is_ascendbooleanOptionalSort direction. Default ascending for name.
limitintegerOptionalPage size. Default 20, min 1, max 100.
offsetintegerOptionalPagination offset. Default 0.

Response

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

Errors

StatusWhen
401Missing/invalid/expired credential
403feature_not_available, permission_denied, guest_not_allowed
429Throttled — Retry-After header set
curl -sS 'https://api.dailybot.com/v1/labels/?order=usage&is_ascend=false&limit=50' \
  -H 'X-API-KEY: $DAILYBOT_API_KEY'

Try it

This is a copy-only helper — the request is not sent from your browser. Paste the command into your terminal to execute it.

POST/v1/labels/API keyCLI Auth

Create a label

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

Request body

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

Response

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

Errors

StatusWhen
400validation_error, invalid_color
401Missing/invalid/expired credential
403feature_not_available, permission_denied, guest_not_allowed
409duplicate_name — a label with this name already exists
429Throttled — Retry-After header set
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"}'

Try it

This is a copy-only helper — the request is not sent from your browser. Paste the command into your terminal to execute it.

GET/v1/labels/{label_uuid}/API keyCLI Auth

Retrieve a label

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

Path parameters

NameTypeRequiredDescription
label_uuidstring (uuid)Required—

Response

{
  "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}"
}

Errors

StatusWhen
401Missing/invalid/expired credential
403feature_not_available, permission_denied, guest_not_allowed
404not_found — label not in caller's organization
429Throttled — Retry-After header set
curl -sS 'https://api.dailybot.com/v1/labels/{label_uuid}/' \
  -H 'X-API-KEY: $DAILYBOT_API_KEY'

Try it

This is a copy-only helper — the request is not sent from your browser. Paste the command into your terminal to execute it.

  • 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}/API keyCLI Auth

Update a label

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

Path parameters

NameTypeRequiredDescription
label_uuidstring (uuid)Required—

Request body

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

Response

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

Errors

StatusWhen
400validation_error, invalid_color
401Missing/invalid/expired credential
403permission_denied
404not_found
409duplicate_name
429Throttled — Retry-After header set
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"}'

Try it

This is a copy-only helper — the request is not sent from your browser. Paste the command into your terminal to execute it.

DELETE/v1/labels/{label_uuid}/API keyCLI Auth

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.

Path parameters

NameTypeRequiredDescription
label_uuidstring (uuid)Required—

Errors

StatusWhen
401Missing/invalid/expired credential
403permission_denied
404not_found
409label_in_use — label is attached to one or more items
429Throttled — Retry-After header set
curl -sS -X DELETE 'https://api.dailybot.com/v1/labels/{label_uuid}/' \
  -H 'X-API-KEY: $DAILYBOT_API_KEY'

Try it

This is a copy-only helper — the request is not sent from your browser. Paste the command into your terminal to execute it.

POST/v1/labels/{label_uuid}/archive/API keyCLI Auth

Archive a label

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

Path parameters

NameTypeRequiredDescription
label_uuidstring (uuid)Required—

Response

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

Errors

StatusWhen
401Missing/invalid/expired credential
403permission_denied
404not_found
429Throttled — Retry-After header set
curl -sS -X POST 'https://api.dailybot.com/v1/labels/{label_uuid}/archive/' \
  -H 'X-API-KEY: $DAILYBOT_API_KEY'

Try it

This is a copy-only helper — the request is not sent from your browser. Paste the command into your terminal to execute it.

  • Use PATCH with is_archived=false on the label detail endpoint to restore an archived label.
GET/v1/labels/{label_uuid}/items/API keyCLI AuthLimit-offset pagination

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

Path parameters

NameTypeRequiredDescription
label_uuidstring (uuid)Required—

Query parameters

NameTypeRequiredDescription
typestringOptionalFilter by item type: forms, automations, checkins.
searchstringOptionalCase-insensitive search on item name.
limitintegerOptionalPage size. Default 20, max 100.
offsetintegerOptionalPagination offset.

Response

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

Errors

StatusWhen
401Missing/invalid/expired credential
403feature_not_available, permission_denied
404not_found
429Throttled — Retry-After header set
curl -sS 'https://api.dailybot.com/v1/labels/{label_uuid}/items/?type=forms' \
  -H 'X-API-KEY: $DAILYBOT_API_KEY'

Try it

This is a copy-only helper — the request is not sent from your browser. Paste the command into your terminal to execute it.

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

CLI & Agent Skill: Use dailybot label … or the dailybot-labels sub-skill (dailybot-cli >= 3.9.0). See /developers/cli and /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:

{
  "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 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