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

# Create a label

`POST /api/v1/labels`

## Query parameters

- `userId` string, uuid — Target user membership ID (for org-scoped API keys)

## Request body

- LabelsCreateBody
  - `color` string, nullable — Hex color for the label (e.g. #0366d6)
  - `description` string, nullable — Label description
  - `homepage` boolean — Show label on homepage. Requires admin permissions.
  - `name` string, required — Label name
  - `verified` boolean — Mark as verified label. Requires admin permissions.

## Response `201`

Label created successfully

- LabelsCreateResponse
  - `color` string, nullable, required — Hex color for the label (e.g. #0366d6)
  - `description` string, nullable, required — Label description
  - `homepage` boolean, required — Whether label is shown on homepage
  - `name` string, required — Label name
  - `usage_count` number, required — Number of documents with this label
  - `verified` boolean, required — Whether label is verified

## Other responses

- `400` — Invalid request body
- `401` — Authentication required
- `403` — Permission denied - cannot create verified/homepage labels without admin permissions
- `409` — Label with this name already exists

---

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