# Contract: Image List Pagination Query

No new API endpoints are introduced. This document records the existing API contract the UI relies on for pagination.

## Endpoint

```
GET /api/v1/images?limit={limit}&offset={offset}&tags={tags}
```

## Parameters

| Parameter | Type    | Required | Description                                      |
|-----------|---------|----------|--------------------------------------------------|
| `limit`   | integer | No       | Images per page. UI sends `24`. Max is 100.      |
| `offset`  | integer | No       | Number of images to skip. UI computes `(page-1) * 24`. |
| `tags`    | string  | No       | Comma-separated tag names for AND-filter.        |

## Response

```json
{
  "items": [ /* ImageRecord[] */ ],
  "total": 143,
  "limit": 24,
  "offset": 48
}
```

| Field    | Type    | Description                                      |
|----------|---------|--------------------------------------------------|
| `total`  | integer | Total images matching the filter (all pages).    |
| `limit`  | integer | Page size echoed back.                           |
| `offset` | integer | Offset echoed back.                              |
| `items`  | array   | Images for this page only.                       |

## UI-Computed Values

```
totalPages = Math.ceil(total / limit)       // e.g. ceil(143 / 24) = 6
currentPage = offset / limit + 1            // e.g. 48 / 24 + 1 = 3
offset = (page - 1) * limit                // e.g. (3 - 1) * 24 = 48
```

## URL State

| Query Param | Source              | Example          |
|-------------|---------------------|------------------|
| `page`      | current page number | `?page=3`        |
| `tags`      | active tag filters  | `?tags=cat,funny` |

Both params coexist: `/?page=3&tags=cat,funny`