---
title: "Create tag value"
method: POST
path: "/v1/tag-values"
tags: ["Tags"]
---

# Create tag value

`POST /v1/tag-values`

Register a grouped tag (key, value) with a palette color before any workflow uses it. The label shows a zero workflow count until applied to a workflow.

## Headers

- `x-api-key` string, nullable — Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.

## Request body

- TagValueCreate — Body for ``POST /v1/tag-values``: register a grouped label before any workflow uses it. The label shows a zero workflow count until applied.
  - `key` string, required — Tag key (group) for the new label.
  - `value` string, required — Tag value (label) to register under the key.
  - `color` string, nullable — Palette color name for the label; a random palette color when omitted.

## Response `200`

Successfully registered tag value

- TagValue — Tag-value color registry entry: the palette color assigned to a grouped (key, value) pair.
  - `key` string, required
  - `value` string, required
  - `color` string, required
  - `workflow_count` integer — Number of non-deleted workflows currently carrying this (key, value) label.

## Other responses

- `409` — Tag value already exists
- `422` — Invalid key, value, or color

## Changes

- **2026-07-22** `5987635eae7d` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/skyvern-ai/apis/skyvern-api-2/changes/v1/tag-values/post.md)

---

[API](https://skmtc.dev/skyvern-ai/apis/skyvern-api-2.md) · [All operations](https://skmtc.dev/skyvern-ai/apis/skyvern-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/skyvern-ai/skyvern-api-2/revisions/d9771d57ea65/schema)