---
title: "Create Label"
method: POST
path: "/labels"
tags: ["Label"]
---

# Create Label

`POST /labels`

Creates a new label in the caller's organization. The label name must be unique within the organization; attempting to create a duplicate returns 409. On a network retry after a successful first request, clients may observe a 409 and should fetch the label by name to confirm creation.

## Request body

- CreateLabelRequest — Payload for creating a new label in the authenticated organization. The organization UUID is derived from the API key and must not be supplied in the body.
  - `name` string, required — Human-readable label name. Trimmed before validation. Must be unique within the organization.
  - `description` string — Optional description of the label. 0 to 2000 characters.
  - `aiFlow` boolean — Whether this label participates in the AI flow (auto-classification during conversation post-processing). Defaults to false.
  - `allTeams` boolean — Whether this label applies to all teams in the organization. Defaults to false.
  - `options` LabelOption[] — Optional set of selectable values when the label is a multi-value enum. Omit or send an empty array for binary labels.
    - `value` string — The option value as displayed to callers. Stored as an arbitrary JSON value server-side; surfaced here as a string for REST ergonomics.
    - `description` string — Optional human-readable description of the option, used for tooltips and AI-flow prompts.

## Response `201`

Label successfully created

- LabelResponse — Single-resource response envelope for label endpoints.
  - `data` Label — A label (label category) used to classify conversations and drive AI flows, scorecard criteria, and intelligence-item-collection criteria. Labels are scoped to a single organization.
    - `uuid` string, required — Unique identifier of the label.
    - `name` string, required — Human-readable label name. Unique per organization. Trimmed; 1 to 128 characters.
    - `description` string — Longer description of the label's meaning or criteria. 0 to 2000 characters.
    - `aiFlow` boolean, required — Whether this label participates in the AI flow (auto-classification during conversation post-processing).
    - `allTeams` boolean, required — Whether this label applies to all teams in the organization. When false, label visibility is constrained by team assignments managed through the internal API.
    - `isDefaultTemplate` boolean, required — Whether this label originated from the organization's default template. Default-template labels are typically managed as a system-seeded group.
    - `options` LabelOption[] — Optional set of selectable values when the label is a multi-value enum. Empty or omitted for binary labels.
      - `value` string — The option value as displayed to callers. Stored as an arbitrary JSON value server-side; surfaced here as a string for REST ergonomics.
      - `description` string — Optional human-readable description of the option, used for tooltips and AI-flow prompts.
    - `organizationUUID` string, required — UUID of the organization that owns the label. Always matches the authenticated principal's organization on responses.
    - `createdAt` string, date-time, required — Timestamp when the label was created, in ISO 8601 (RFC 3339) format.

## Other responses

- `400` — Invalid request body (missing name, name too long, description too long, or invalid option shape)
- `401` — Authentication failed. Please provide a valid organization-scoped API key.
- `409` — A label with the same name already exists in the organization
- `422` — Schema-level validation failure (e.g. body fails minLength/maxLength). Returned before handler-level business rules are applied.
- `500` — Unexpected server error. Please try again later.
- `default` — Unexpected error occurred while creating the label

---

[API](https://skmtc.net/attention/apis/attention-service-v2.md) · [All operations](https://skmtc.net/attention/apis/attention-service-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/attention/attention-service-v2/versions/5de55d3804cf/schema)