# Contract: GET /api/v1/tags (enhanced)

## Overview

Extends the existing tags list endpoint with two new optional query parameters. All existing behaviour is preserved when the new parameters are omitted.

## Request

```
GET /api/v1/tags
```

### Query Parameters

| Parameter  | Type    | Default  | Description |
|------------|---------|----------|-------------|
| `q`        | string  | —        | Filter tags by name prefix (existing) |
| `limit`    | integer | 100      | Max items to return; capped at 200 (existing) |
| `offset`   | integer | 0        | Pagination offset (existing) |
| `sort`     | string  | `name`   | Sort order: `name` (alphabetical asc) or `count_desc` (image count descending, alphabetical secondary) |
| `min_count`| integer | 0        | Exclude tags with fewer than this many images. Use `1` to hide zero-count tags. |

### Authentication

Not required. Public endpoint.

## Response

```json
{
  "items": [
    { "id": "uuid", "name": "string", "image_count": 0 }
  ],
  "total": 0,
  "limit": 100,
  "offset": 0
}
```

No changes to the response shape.

## Tag Browser Usage

The tag browser component calls:

```
GET /api/v1/tags?sort=count_desc&min_count=1&limit=500
```

`limit=500` is a safe upper bound for a personal library. If `total` exceeds `limit` in the response, the component logs a warning but renders what it received (no pagination UI required at this scale).

## Library Autocomplete Usage (unchanged)

```
GET /api/v1/tags?q=<prefix>&limit=10
```

Uses neither `sort` nor `min_count` — default behaviour is unchanged.
