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

# Create tag value

`POST /v1/tag-values`

## Request

- Base URL: `https://api.skyvern.com`
- URL: `https://api.skyvern.com/v1/tag-values`
- Auth: none declared

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-10-08** `04df18172f4d`: 1 info
  - endpoint added

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

---

[API](https://skmtc.dev/skyvern-ai/apis/skyvern-api.md) - [All operations](https://skmtc.dev/skyvern-ai/apis/skyvern-api/llms.txt) - [OpenAPI document](https://skmtc.dev/skyvern-ai/apis/skyvern-api/revisions/22eb83913dde?raw)