(PUT) Update/Upsert tags

Update existing tags or create new ones with upsert operations.

Endpoint

PUT /api/tags

Upsert (update or insert) one or more tags. If id is provided, the tag is updated. If the ID does not exist, the request fails. To create new tags, omit the id field.

This endpoint is useful for synchronization scenarios where you want to ensure tags exist with specific properties.

Endpoint text

PUT /api/tags

Authentication

Requires authentication with an API key that has the tagsWrite scope.

Request Body

The request body must be an array of tag objects. Include the id field to update an existing tag, or omit it to create a new one.

You can upsert up to 10,000 tags in a single request. However, the actual maximum may be lower based on your subscription plan limits and available resources.

Parameter	Type	Required	Description
`id` (body)	string (UUID)	Yes	Required when updating. Omit to create a new tag. If provided, it must exist in your workspace or the request fails.
`name` (body)	string	No	The name of the tag. Required when creating a new tag (no id). Optional when updating.
`color` (body)	string	No	The color of the tag. Optional. Defaults to \"slate\" when creating a new tag.

Update Behavior

When updating, only the fields you include are changed. Omitted fields keep their current values. For new tags (no id), color defaults to \"slate\" if omitted.

Plan Limits

The actual maximum number of tags you can upsert per request may be lower than 10,000 based on your subscription plan limits and available resources. The system will enforce both the hard limit (10,000) and your plan-specific limits.

Examples

Available Colors

slate

gray

zinc

neutral

stone

red

orange

amber

yellow

lime

green

emerald

teal

cyan

sky

blue

indigo

violet

purple

fuchsia

pink

rose

Request cURL

curl -X PUT "https://hoko.to/api/tags" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Updated Tag",
      "color": "green"
    }
  ]'

Request JavaScript

const response = await fetch("https://hoko.to/api/tags", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer <API_KEY>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify([
    {
      id: "550e8400-e29b-41d4-a716-446655440000",
      name: "Updated Tag",
      color: "green"
    }
  ])
});
const tags = await response.json();

Response json

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Updated Tag",
    "color": "green"
  }
]