---
title: "Bulk update document labels"
method: PATCH
path: "/v1/documents/{documentId}/labels"
tags: ["Document labels"]
---

# Bulk update document labels

`PATCH /v1/documents/{documentId}/labels`

Add and/or remove multiple labels from a document in a single atomic operation.

## Path parameters

- `documentId` string, uuid, required

## Query parameters

- `userId` string

## Request body

- object
  - `add` string[] — Label names to add to the document
  - `remove` string[] — Label names to remove from the document

## Response `200`

Labels updated successfully

- object
  - `labels` string[] — The updated list of labels on the document

## Other responses

- `400` — Bad Request. Possible causes: - Empty request - Neither `add` nor `remove` contains any labels - Label appears in both `add` and `remove` arrays - Invalid label name (less than 2 or more than 25 characters)
- `403` — Forbidden. Possible causes: - User does not have `canLabel` permission on the document - User lacks Organization Admin permissions to modify Verified labels - User lacks Organization Admin permissions to modify Homepage labels
- `404` — Not Found. Possible causes: - Document does not exist - Label does not exist globally. Create the label first with the [Create label API](/api/labels/create-label). - Label in `remove` array does not exist on the document
- `429` — Too Many Requests - Rate limit exceeded (60 requests/minute)

---

[API](https://skmtc.net/omni/apis/omni-api.md) · [All operations](https://skmtc.net/omni/apis/omni-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/omni/omni-api/revisions/6b02f7349d0e/schema)