---
title: "Merge a label into another"
method: POST
path: "/labels/{labelId}/merge"
tags: ["Labels"]
---

# Merge a label into another

`POST /labels/{labelId}/merge`

## Request

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

Requires both **Labels: Update** and **Labels: Delete**. Moves every use of the label in the path onto `targetLabelId`, then archives it with `mergedInto` set. A passage that already had both labels keeps one. A merged label cannot be restored.

`movedCount` is the number of labelled passages changed across the whole company.

#### Errors

- `400` when the two ids are the same, when either is a group, or when either is archived.
- `403` without both permissions.
- `404` when either label does not exist.

## Path parameters

- `labelId` string, required

## Request body

- object
  - `targetLabelId` string, required: Id of the label to keep. 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.

## Response `200`

Success

- object
  - `status` 'success': `success` on every 2xx response.
  - `data` object: The result.
    - `labelId` string: Id of the label that was merged and archived.
    - `mergedInto` string: Id of the label that now carries its uses.
    - `movedCount` integer: Labelled passages changed, company-wide.

## Other responses

- `400`: Same label, a group, or an archived label
- `403`: You lack Labels: Update or Labels: Delete
- `404`: Either label does not exist

---

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