---
title: "Create Tag"
method: POST
path: "/tags"
tags: ["Tags"]
---

# Create Tag

`POST /tags`

Create a new tag

## Headers

- `X-Buttondown-Collision-Behavior` 'no_op' | 'overwrite' — Behavior applied when a tag with the same name already exists on create.

## Request body

- TagInput — Input schema for creating a new tag.
  - `name` string, required — The name of the tag.
  - `color` string, required — The hex color code associated with the tag.
  - `description` string, nullable — An internal description of the tag, only visible to the newsletter author.
  - `public_description` string, nullable — A public-facing description of the tag, visible to subscribers in the subscriber portal.
  - `subscriber_editable` boolean — If true, subscribers can add or remove this tag from their own profile via the subscriber portal.

## Response `200`

OK

- Tag — Tags are a way to organize your subscribers. You can create, update, and delete tags via the API. You can also list all tags for a given newsletter. Tags don't have any strict functionality on their own, but you can send emails to subscribers with a given tag (or to all subscribers _without_ a given tag.)
  - `id` string, required — A unique TypeID associated with the object.
  - `creation_date` string, date-time, required — The date and time at which the object was first created.
  - `name` string, required — The name of the tag.
  - `color` string, required — The hex color code associated with the tag.
  - `description` string, nullable — An internal description of the tag, only visible to the newsletter author.
  - `public_description` string, nullable — A public-facing description of the tag, visible to subscribers in the subscriber portal.
  - `subscriber_editable` boolean, required — If true, subscribers can add or remove this tag from their own profile via the subscriber portal.
  - `secondary_id` integer, required — The secondary ID of the tag, used as a human-readable numeric identifier.

## Other responses

- `201` — Created
- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `409` — Conflict
- `422` — Unprocessable Entity
- `429` — Too Many Requests

## Changes

- **2026-08-04** `bed30b2b43bc` — 1 warning
  - changed the pattern of the request property `name` from `^[ -~]*[A-Za-z0-9][ -~]*$` to `^[^\x00-\x1f\x7f-\x9f]*[^\W_][^\x00-\x1f\x7f-\x9f]*$`

[Change history](https://skmtc.dev/buttondown/apis/buttondown-api/changes/tags/post.md)

---

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