---
title: "Create a label or group"
method: POST
path: "/labels"
tags: ["Labels"]
---

# Create a label or group

`POST /labels`

## Request

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

Requires the **Labels: Create** permission (on by default for admins and members).

#### Request rules

- Send `isGroup: true` to create a group. A group cannot have `color` or `parentId`; sending either returns 400.
- `parentId` must be the `labelId` of an active group in your company. A missing group returns 404 "Parent group not found."; a label that is not a group returns 400 "A label can only be placed inside a group."
- `color` defaults to `#6366f1` when you leave it out.
- `sortOrder` defaults to 0.

#### Errors

- `400` when a field fails validation or the parent is not a group.
- `403` without the permission.
- `404` when the parent group does not exist.
- `409` when an active label with the same name already exists under the same parent. Names are compared ignoring case, after trimming and collapsing spaces.

## Request body

- object
  - `name` string, required: 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.
  - `isGroup` boolean: `true` to create a group instead of a label. Defaults to `false`.
  - `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 the group to put the label in. `null` or left out for the top level. Not allowed on a group. 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`: The request failed validation
- `403`: You lack the Labels: Create permission
- `404`: The parent group does not exist
- `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)