# Tags

Tags are user-scoped labels attachable to contacts. Each tag has a name and an
optional hex color. Tag deletion against an in-use tag returns 409 unless
`force=true` is sent.

## List tags

`GET /api/tags`

Returns all tags owned by the authenticated user, sorted alphabetically.
Each tag includes the count of associated contacts.

### Example request

```bash
curl --request GET \
    --get "https://klozzo.com/api/tags" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
```

### Response `200`

```json
{
    "data": [
        {
            "id": null,
            "name": "aut",
            "slug": null,
            "color": "#a11e59",
            "location_id": null,
            "created_at": null,
            "updated_at": null
        },
        {
            "id": null,
            "name": "modi",
            "slug": null,
            "color": "#865450",
            "location_id": null,
            "created_at": null,
            "updated_at": null
        }
    ]
}
```

## Create a tag

`POST /api/tags`

Tags are the free-form way to group people: a campaign, an event, a list
you built by hand. Use them for something you will want to filter by later
but that has no value of its own — when the thing you want to record *has*
a value ("budget", "plan", "renewal date"), a custom field is what you
want instead.

The name is unique inside the location; creating one that already exists
answers `422` rather than a second tag with the same name.

### Body parameters

- `name` (string, required) — Tag name (max 255).
- `color` (string) — Hex color including the `#` prefix.

### Example request

```bash
curl --request POST \
    "https://klozzo.com/api/tags" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"VIP\",
    \"color\": \"#ff6b35\"
}"
```

### Response `200`

```json
{
    "data": {
        "id": null,
        "name": "nihil",
        "slug": null,
        "color": "#c8a15d",
        "location_id": null,
        "created_at": null,
        "updated_at": null
    }
}
```

### Response `422` — A colour that is not a hex code

```json
{
    "message": "Color no tiene un formato válido.",
    "errors": {
        "color": [
            "Color no tiene un formato válido."
        ]
    }
}
```

### Response `422` — A name already used in this location

```json
{
    "message": "El valor de name ya está en uso.",
    "errors": {
        "name": [
            "El valor de name ya está en uso."
        ]
    }
}
```

## Fetch a tag

`GET /api/tags/{id}`

Returns one tag by id, with how many contacts carry it. Useful before deleting one: the
count is what tells you whether removing it is housekeeping or data loss.

### Path parameters

- `id` (integer, required) — Tag ID.

### Example request

```bash
curl --request GET \
    --get "https://klozzo.com/api/tags/3" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
```

### Response `200`

```json
{
    "data": {
        "id": null,
        "name": "adipisci",
        "slug": null,
        "color": "#f76df4",
        "location_id": null,
        "created_at": null,
        "updated_at": null
    }
}
```

### Response `404` — Does not exist, or belongs to another location

```json
{
    "message": "No query results for model."
}
```

## Update a tag

`PUT /api/tags/{id}`

Updates a tag's name or colour by id. **Every contact carrying the tag sees
the new name immediately** — a tag is one row, not a copy per contact — so
renaming is how you fix a typo, never how you split a group in two.

### Path parameters

- `id` (integer, required) — Tag ID.

### Body parameters

- `name` (string) — Tag name (max 255).
- `color` (string) — Hex color including the `#` prefix.

### Example request

```bash
curl --request PUT \
    "https://klozzo.com/api/tags/3" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"VIP Customer\",
    \"color\": \"#ff6b35\"
}"
```

### Response `200`

```json
{
    "data": {
        "id": null,
        "name": "accusantium",
        "slug": null,
        "color": "#902510",
        "location_id": null,
        "created_at": null,
        "updated_at": null
    }
}
```

## Delete a tag

`DELETE /api/tags/{id}`

Deletes a tag by id. If the tag is attached to any contacts, returns 409
unless `force=true` is
passed, in which case the tag is detached from all contacts then deleted.

### Path parameters

- `id` (integer, required) — Tag ID.

### Query parameters

- `force` (boolean) — Detach from contacts and delete anyway.

### Example request

```bash
curl --request DELETE \
    "https://klozzo.com/api/tags/3?force=1" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
```

### Response `200`

```json
{
    "message": "Tag deleted."
}
```

### Response `409` — tag in use

```json
{
    "message": "Tag is in use.",
    "contacts_count": 12,
    "hint": "Pass force=true to detach and delete."
}
```