---
title: "Create label"
method: POST
path: "/v1/labels"
tags: ["Labels"]
---

# Create label

`POST /v1/labels`

Create a new label in the organization.

Any user can create basic labels, but **Organization Admin** permissions are required to:

- Create **Verified** labels (`verified: true`)
- Create **Homepage** labels (`homepage: true`)

## Query parameters

- `userId` string

## Request body

- object
  - `name` string, required — Label name. Must be 2-25 characters. Names are case-insensitive: `"Production"` and `"production"` are considered the same.
  - `color` string — Hex color for the label
  - `description` string — Description of the label
  - `verified` boolean — **Requires Organization Admin permissions**. If `true`, documents with this label will be marked as verified/curated.
  - `homepage` boolean — **Requires Organization Admin permissions**. If `true`, documents with this label will display on the instance's Homepage.

## Response `201`

Label created successfully

- Label — A label for organizing and categorizing documents and folders
  - `name` string — The label name (2-25 characters). Names are case-insensitive: `"Production"` and `"production"` are considered the same.
  - `verified` boolean — Whether the label is verified/curated
  - `homepage` boolean — Whether the label appears on the organization homepage
  - `usage_count` integer — Total number of documents and folders using this label
  - `color` string — Hex color for the label
  - `description` string — Description of the label

## Other responses

- `400` — Bad Request. Possible causes: - Label name too short (less than 2 characters) - Label name too long (more than 25 characters)
- `403` — Forbidden. Possible causes: - User lacks **Organization Admin** permissions, which are required to create Verified and Homepage labels - User lacks the permissions required to manage labels
- `409` — Conflict. A label with this name already exists (case-insensitive).
- `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)