# Tags

> Label and group your templates.

Tags organise templates. Create them, search them, and attach them to templates. All tags are scoped to your company.

## List tags

```http
GET /v1/tags
```

Returns up to 15 tags, ordered by name, optionally filtered by a search term.

- **Auth:** Bearer token
- **Token abilities:** `api_requests`
- **Gates:** logApiRequest
- **Credits:** Free — no credits consumed.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `search` | query | string | No | Case-insensitive substring match on tag name. |

### Responses

**200** — Matching tags.

```json
{
    "data": [
        {
            "id": 1,
            "name": "Launch",
            "slug": "launch"
        }
    ]
}
```

### Examples

*Curl*

```bash
curl 'https://snapsbrew.com/api/v1/tags?search=launch' \
  -H 'Authorization: Bearer <your-token>'
```

## Create a tag

```http
POST /v1/tags
```

Creates a tag. The slug is generated from the name; collisions get a numeric suffix.

- **Auth:** Bearer token
- **Token abilities:** `api_requests`
- **Gates:** logApiRequest
- **Credits:** Free — no credits consumed.

### Request body

Content-Type: `application/json`

| Field | Type | Required | Validation | Description |
| --- | --- | --- | --- | --- |
| `name` | string | Yes | required, string, max:255 | Display name of the tag. |

### Responses

**201** — Tag created.

```json
{
    "data": {
        "id": 1,
        "name": "Launch",
        "slug": "launch"
    }
}
```

**422** — Validation failed.

```json
{
    "message": "The name field is required."
}
```

### Examples

*Curl*

```bash
curl -X POST https://snapsbrew.com/api/v1/tags \
  -H 'Authorization: Bearer <your-token>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Launch"}'
```

## Sync template tags

```http
POST /v1/templates/{templateUuid}/tags
```

Replaces all tags on a template with the supplied set. Send an empty array to clear every tag.

- **Auth:** Bearer token
- **Token abilities:** `api_requests`
- **Gates:** logApiRequest
- **Credits:** Free — no credits consumed.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `templateUuid` | path | string | Yes | UUID of the template. |

### Request body

Content-Type: `application/json`

| Field | Type | Required | Validation | Description |
| --- | --- | --- | --- | --- |
| `tag_ids` | integer[] | No | array | Tag IDs to attach. Replaces the existing set. |
| `tag_ids.*` | integer | No | integer, exists tags.id scoped to company | Each ID must belong to your company. |

### Responses

**200** — Tags synced.

```json
{
    "message": "Tags updated successfully.",
    "tags": [
        {
            "id": 1,
            "name": "Launch",
            "slug": "launch"
        }
    ]
}
```

**404** — Template not found in your company.

```json
{
    "message": "Not found."
}
```

**422** — A tag ID is invalid or not yours.

```json
{
    "message": "The selected tag_ids.0 is invalid."
}
```

### Examples

*Curl*

```bash
curl -X POST https://snapsbrew.com/api/v1/templates/<uuid>/tags \
  -H 'Authorization: Bearer <your-token>' \
  -H 'Content-Type: application/json' \
  -d '{"tag_ids":[1,2]}'
```