---
title: "Update Label"
method: PATCH
path: "/labels/{id}"
tags: ["Label"]
---

# Update Label

`PATCH /labels/{id}`

Partially updates a label. Only fields present in the request body are applied (pointer-nil merge semantics). Renaming a label cascades updates to scorecard criteria and intelligence-item-collection criteria that reference the old label name. Cross-organization updates return 404.

## Path parameters

- `id` string, required

## Request body

- UpdateLabelRequest — Payload for partially updating a label. Only fields present in the body are applied (pointer-nil merge semantics). At least one mutable field must be provided.
  - `name` string — New label name. Trimmed before validation. Must be unique within the organization. Renaming cascades to scorecard criteria and intelligence-item-collection criteria that reference the old name.
  - `description` string, nullable — New description. Pass an empty string to clear. 0 to 2000 characters. Omit to leave unchanged.
  - `aiFlow` boolean, nullable — New AI-flow participation value. Omit to leave unchanged.
  - `allTeams` boolean, nullable — New allTeams value. Omit to leave unchanged.
  - `options` LabelOption[] — New option set. When provided, the full list replaces the existing options. Omit to leave unchanged; send an empty array to clear.
    - `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 `200`

Label successfully updated

- 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 (empty update, name too long, description too long, or invalid option shape)
- `401` — Authentication failed. Please provide a valid organization-scoped API key.
- `404` — Label not found in the caller's organization
- `409` — Another label in the organization already uses the requested name
- `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 updating 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)