---
title: "Update a label or group"
method: PUT
path: "/labels/{labelId}"
tags: ["Labels"]
---

# Update a label or group

`PUT /labels/{labelId}`

## Request

- Base URL: `https://api.speakai.co/v1`
- URL: `https://api.speakai.co/v1/labels/{labelId}`
- Auth: API key in header `x-speakai-key` and API key in header `x-access-token`

Requires the **Labels: Update** permission (on by default for admins and members). Send at least one field; an empty body returns 400. Only the fields you send change.

#### Request rules

- An archived label cannot be edited: restore it first (400 "Restore this label before editing it.").
- A group has no colour and cannot be placed inside another group (400).
- `parentId` moves a label into a group; `null` moves it to the top level. A label cannot be its own group (400).

#### Errors

- `400` for the rules above or a field that fails validation.
- `403` without the permission.
- `404` when the label or the new parent group does not exist.
- `409` when the new name is already used by an active label under the same parent.

## Path parameters

- `labelId` string, required

## Request body

- object
  - `name` string: Name of the label or group. Trimmed, then 1 to 80 characters. Repeated spaces are collapsed to one before saving. Names are unique among active labels with the same parent, compared without regard to case, so a duplicate returns 409.
  - `description` string: What the label means, shown to people choosing it. Up to 500 characters after trimming. An empty string is accepted.
  - `color` string: Colour as six-digit hex, `#rrggbb` (pattern `^#[0-9a-fA-F]{6}$`). Stored in lower case. Not allowed on a group.
  - `parentId` string, nullable: `labelId` of a group to move the label into, or `null` to move it to the top level. Trimmed, then 1 to 64 characters from `A-Z`, `a-z`, `0-9`, `_` and `-` (pattern `^[A-Za-z0-9_-]{1,64}$`). Anything else returns 400.
  - `sortOrder` integer: Position among its siblings, lowest first. Integer from 0 to 1,000,000. Labels with the same value are ordered by name.

## Response `200`

Success

- object
  - `status` 'success': `success` on every 2xx response.
  - `data` object: A label or group.
    - `labelId` string: Id of the label or group.
    - `isGroup` boolean: `true` for a group. A group holds labels and cannot be applied to a transcript.
    - `name` string: Name.
    - `description` string: Description. Left out when none was set.
    - `color` string: `#rrggbb` in lower case. Groups have none.
    - `parentId` string, nullable: `labelId` of the group this label sits in, or `null` at the top level.
    - `source` 'user' | 'speak': `speak` for labels added from a Speak label set, `user` for everything else.
    - `isActive` boolean: `false` once archived.
    - `mergedInto` string: `labelId` this label was merged into. Present only on merged labels.
    - `sortOrder` integer: Position among its siblings.
    - `userId` string: Id of the person who created it.
    - `createdAt` string, date-time: When it was created.
    - `updatedAt` string, date-time: When it last changed.

## Other responses

- `400`: A rule above was broken or a field failed validation
- `403`: You lack the Labels: Update permission
- `404`: No label with that id in your company
- `409`: An active label with this name already exists under the same parent

---

[API](https://skmtc.dev/speakai/apis/speak-ai-api.md) · [All operations](https://skmtc.dev/speakai/apis/speak-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/speakai/apis/speak-ai-api/revisions/52d777e6d46e?raw)