(PUT) Update/Upsert tags

Update existing tags or create new ones with upsert operations.

Endpoint

PUT /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 /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.

ParameterTypeRequiredDescription
id (body)string (ULID)YesRequired when updating. Omit to create a new tag. If provided, it must exist in your workspace or the request fails.
name (body)stringNoThe name of the tag. Required when creating a new tag (no id). Optional when updating.
color (body)stringNoThe color of the tag. Optional. Defaults to \"slate\" when creating a new tag.

Update Behavior

When updating, include at least one mutable field besides id. 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

  • slate
  • gray
  • zinc
  • neutral
  • stone
  • red
  • orange
  • amber
  • yellow
  • lime
  • green
  • emerald
  • teal
  • cyan
  • sky
  • blue
  • indigo
  • violet
  • purple
  • fuchsia
  • pink
  • rose

Available Colors

Type: color

Request cURL 
curl -X PUT "https://api.hoko.to/tags" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": "<tag_id>",
      "name": "Updated Tag",
      "color": "green"
    }
  ]'
Request JavaScript 
const response = await fetch('https://api.hoko.to/tags', {
	method: 'PUT',
	headers: {
		Authorization: 'Bearer <API_KEY>',
		'Content-Type': 'application/json'
	},
	body: JSON.stringify([
		{
			id: '<tag_id>',
			name: 'Updated Tag',
			color: 'green'
		}
	])
});
const tags = await response.json();
Response json 
[
	{
		"id": "<tag_id>",
		"name": "Updated Tag",
		"color": "green"
	}
]