# List Media Items

Retrieve a paginated list of media items, scoped to a library or across all libraries.

**Endpoint**: `GET /api/media-items`
**Auth**: Required

## Query Parameters

| Parameter  | Type   | Required | Description                                            |
| ---------- | ------ | -------- | ------------------------------------------------------ |
| library_id | string | No       | Library UUID. If omitted, items from all libraries are returned |
| limit      | int    | No       | Items to return (default 50, max 1000)                 |
| offset     | int    | No       | Items to skip (must be >= 0)                           |
| sort       | string | No       | Sort expression, default `created_at DESC`             |

### Allowed sort expressions

`created_at`, `title`, `author`, `series`, `date_published`, `copyright_year`, `page_count`, `genre` — each with ` ASC` or ` DESC` (e.g. `title ASC`). Any other value silently falls back to `created_at DESC`.

## Request Headers

| Header        | Type   | Required | Description  |
| ------------- | ------ | -------- | ------------ |
| Authorization | string | Yes      | Bearer token |

### Example Request

```http
GET /api/media-items?library_id=uuid&limit=20&offset=0&sort=title%20ASC
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

## Response (200 OK)

The response body is `{"data": [...]}` in both modes. The item shape differs by mode.

**No total is returned** — page until fewer items than `limit` come back.

### With `library_id` — full database rows

Nullable columns serialize as `null`.

```json
{
  "data": [
    {
      "id": "uuid",
      "library_id": "uuid",
      "title": "Book Title",
      "author": "Author Name",
      "isbn": "978-...",
      "description": "Book description",
      "file_path": "relative/path/book.epub",
      "file_size": 1024000,
      "mime_type": "application/epub+zip",
      "cover_image_path": "relative/path/cover.jpg",
      "series": "Series Name",
      "series_number": 1,
      "tags": ["sci-fi"],
      "asin": null,
      "date_published": "2023-06-01",
      "publisher": null,
      "contributors": ["Author Name"],
      "language": "en",
      "edition": null,
      "page_count": 350,
      "genre": "Science Fiction",
      "copyright_year": 2023,
      "goodreads_id": null,
      "openlibrary_id": null,
      "google_books_id": null,
      "added_by_admin_id": "uuid",
      "created_at": "2026-01-31T10:00:00Z",
      "imported_at": "2026-01-31T10:00:00Z",
      "updated_at": "2026-01-31T10:00:00Z",
      "format_group": "epub",
      "format_mimetype": "application/epub+zip",
      "is_reflowable": true,
      "has_fixed_layout": false,
      "total_characters": 480000,
      "chapter_count": 24
    }
  ]
}
```

Note: in this mode `file_path` and `cover_image_path` are the raw relative storage paths, not URLs.

### Without `library_id` — curated items with resolved URLs

Across all libraries; file and cover paths are resolved to fetchable URL paths (`/uploads/...` or library-scoped paths):

```json
{
  "data": [
    {
      "id": "uuid",
      "library_id": "uuid",
      "title": "Book Title",
      "author": "Author Name",
      "isbn": "978-...",
      "description": "Book description",
      "file_path": "/api/libraries/<uuid>/files/...",
      "file_size": 1024000,
      "mime_type": "application/epub+zip",
      "cover_image_path": "/api/libraries/<uuid>/files/.../cover.jpg",
      "series": "Series Name",
      "series_number": 1,
      "tags": ["sci-fi"],
      "asin": null,
      "date_published": "2023-06-01",
      "publisher": null,
      "contributors": ["Author Name"],
      "language": "en",
      "edition": null,
      "page_count": 350,
      "genre": "Science Fiction",
      "created_at": "2026-01-31T10:00:00Z",
      "updated_at": "2026-01-31T10:00:00Z",
      "format_group": "epub",
      "manga_type": null,
      "reading_direction": null,
      "series_count": null,
      "volume": null,
      "imprint": null,
      "age_rating": null,
      "web_url": null,
      "metadata_notes": null,
      "community_rating": null,
      "story_arc": null,
      "is_black_and_white": false,
      "alternate_info": null,
      "scan_information": null,
      "summary": null
    }
  ]
}
```

## Error Responses

| Code | Description                                |
| ---- | ------------------------------------------ |
| 400  | Invalid `library_id`, `offset` < 0         |
| 401  | Invalid or expired token                   |
| 500  | Query failure (returned as `{"error": …}`) |