> ## Documentation Index
> Fetch the complete documentation index at: https://docs.daysync.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tags

> Create and manage the tags that label a tour's schedule items.

**Tags** are coloured labels defined per tour and attached to **schedule items**. No other resource is taggable.

Tags are gated by the **schedule** scopes rather than a scope of their own, so any integration that can already read or write schedule items can use them without a new grant.

All endpoints require the standard [authentication](/authentication) headers.

***

## List tags

```text theme={null}
GET /v1/tours/{tourId}/tags
```

Returns every tag defined on the tour. Tag IDs are per-tour — read them here before assigning.

**Scope:** `schedule.read`

**Example**

```bash theme={null}
curl "$BASE/v1/tours/2f1c…/tags" \
  -H "x-api-key: $KEY" -H "x-api-secret: $SECRET" -H "Authorization: Bearer $TOKEN"
```

**Response `data`** — array of tags:

```json theme={null}
{
  "id": 1340,
  "name": "Press",
  "is_deleted": false,
  "created_at": "2026-08-06T09:53:52.429Z",
  "color": { "id": 2, "type": "red", "description": "red" }
}
```

***

## Create a tag

```text theme={null}
POST /v1/tours/{tourId}/tags
```

**Scope:** `schedule.write`

**Body**

| Field     | Type   | Required | Description                  |
| --------- | ------ | -------- | ---------------------------- |
| `name`    | string | Yes      | Tag label, 1–100 characters. |
| `colorId` | number | Yes      | An `AvatarColor` ID.         |

<Note>
  `colorId` comes from [`GET /v1/reference/types`](/endpoints/reference), group `avatarColors`. There is no separate tag-colour palette.
</Note>

**Response `data`:**

```json theme={null}
{ "id": 1340, "name": "Press", "color": { "id": 2, "type": "red", "description": "red" } }
```

***

## Update a tag

```text theme={null}
PUT /v1/tours/{tourId}/tags/{tagId}
```

**Scope:** `schedule.write`

**Body** — both optional; send only what changes. An omitted field is left as-is.

| Field     | Type   | Description           |
| --------- | ------ | --------------------- |
| `name`    | string | New label.            |
| `colorId` | number | New `AvatarColor` ID. |

**Response `data`:** the updated tag.

***

## Delete a tag

```text theme={null}
DELETE /v1/tours/{tourId}/tags/{tagId}
```

**Scope:** `schedule.write`

<Warning>
  This is a **hard delete**. The tag is removed from every schedule item that carries it and cannot be restored — unlike most Daysync deletes, which are soft. Check [tag usage](#count-a-tag-s-usage) first.
</Warning>

**Response `data`:** none.

***

## Count a tag's usage

```text theme={null}
GET /v1/tours/{tourId}/tags/{tagId}/usage
```

How many schedule items currently carry the tag. Use before deleting.

**Scope:** `schedule.read`

**Response `data`:**

```json theme={null}
{ "tagId": 1340, "usageCount": 12 }
```

***

## Set an item's tags

```text theme={null}
PUT /v1/schedule/items/{itemId}/tags
```

**Scope:** `schedule.write`

**Body**

| Field    | Type          | Required | Description                        |
| -------- | ------------- | -------- | ---------------------------------- |
| `tourId` | string (UUID) | Yes      | The tour that owns the tags.       |
| `tagIds` | number\[]     | Yes      | The complete tag set for the item. |

<Warning>
  `tagIds` **replaces** the item's entire tag set — it is not a delta. Send every tag the item should end up with. Sending `[]` clears all of them.

  Read the current set from `schedule_item_tags` on [`GET .../schedule`](/endpoints/schedule) first.
</Warning>

**Example** — add tag `1340` to an item that already has `55`:

```bash theme={null}
curl -X PUT "$BASE/v1/schedule/items/205679/tags" \
  -H "x-api-key: $KEY" -H "x-api-secret: $SECRET" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "tourId": "2f1c…", "tagIds": [55, 1340] }'
```

**Response `data`:** none.

A tag belonging to a different tour is rejected with `400`; an unknown tag ID with `404`.

***

## Tagging at creation time

`POST /v1/schedule/items` accepts a `tagIds` array directly, so a new item can be created already tagged:

```json theme={null}
{ "tour_id": "2f1c…", "day_id": 1843, "name": "Load in", "tagIds": [1340] }
```

<Note>
  Inline `tagIds` on create is **lenient**: unknown or foreign tag IDs are silently skipped and the item is still created. `PUT /v1/schedule/items/{itemId}/tags` is **strict** and rejects them. If you need to know a tag actually landed, use the dedicated endpoint or read the item back.
</Note>

## Reading tags back

Tags appear on every schedule item returned by [`GET /v1/tours/{tourId}/days/{dayId}/schedule`](/endpoints/schedule):

```json theme={null}
"schedule_item_tags": [
  { "tag": { "id": 1340, "name": "Press", "color": { "id": 2, "type": "red", "description": "red" } } }
]
```

***

See also: [Schedule](/endpoints/schedule), [Reference Data](/endpoints/reference).