Create Tag

Changed on Aug 4, 2026

Create a new tag

post/tags

Request

Base URL
https://api.buttondown.com/v1
URL
https://api.buttondown.com/v1/tags
Auth
API key in header Authorization

Headers

X-Buttondown-Collision-Behavior'no_op' | 'overwrite'

Behavior applied when a tag with the same name already exists on create.

The behavior to apply when a tag with the same name already exists. Defaults to "no_op", which returns a 400 error. Set to "overwrite" to update the existing tag with the supplied values and return it with a 200 status code instead.

Request body

namestring required

The name of the tag.

colorstring required

The hex color code associated with the tag.

descriptionstring nullable

An internal description of the tag, only visible to the newsletter author.

public_descriptionstring nullable

A public-facing description of the tag, visible to subscribers in the subscriber portal.

subscriber_editableboolean

If true, subscribers can add or remove this tag from their own profile via the subscriber portal.

Example request

{
  "name": "VIP",
  "color": "#FFD700"
}

Response

idstring required

A unique TypeID associated with the object.

creation_datestring date-time required

The date and time at which the object was first created.