# Create Media Item

Create a new media item (Admin only).

**Endpoint**: `POST /api/media-items`
**Auth**: Required (Admin only)
**Content-Type**: `application/json`

## Prerequisites

**Before creating media items**, the library must have at least one folder configured:

1. Create a library: `POST /api/libraries`
2. Add folder(s) to the library: `POST /api/libraries/{library_id}/folders`
3. Then create media items: `POST /api/media-items`

See [Library API documentation](../libraries/) for more details.

## Request Body

| Field            | Type             | Required | Description                           |
| ---------------- | ---------------- | -------- | ------------------------------------- |
| library_id       | string (UUID)    | Yes      | Library UUID to add the media item to |
| title            | string           | Yes      | Media item title (1-500 characters)   |
| author           | string           | No       | Author name                           |
| isbn             | string           | No       | ISBN number                           |
| description      | string           | No       | Description or summary                |
| file_path        | string           | Yes      | Path to the media file                |
| file_size        | integer          | Yes      | Size of the file in bytes             |
| mime_type        | string           | Yes      | MIME type of the file                 |
| cover_image_path | string           | No       | Path to the cover image               |
| series           | string           | No       | Series name                           |
| series_number    | integer          | No       | Number in the series                  |
| tags             | array of strings | No       | Tags (auto-normalized)                |
| asin             | string           | No       | Amazon ASIN                           |
| date_published   | string           | No       | Publication date                      |
| publisher        | string           | No       | Publisher name                        |
| contributors     | array of strings | No       | Contributors (auto-normalized)        |

## Tag/Contributor Normalization

Tags and contributors are automatically normalized:

- **Tags**: Titlecased, punctuation preserved, case-insensitive deduplication
- **Contributors**: Original casing and punctuation preserved, case-insensitive deduplication
- **Search fields**: Auto-generated for case-insensitive search

### Example Request

```json
{
  "library_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Example Book Title",
  "author": "Jane Doe",
  "isbn": "978-0-123456-78-9",
  "description": "A great book about technology",
  "file_path": "/library/books/example.epub",
  "file_size": 1048576,
  "mime_type": "application/epub+zip",
  "series": "Tech Series",
  "series_number": 1,
  "tags": ["science-fiction", "technology", "ACME CORP."],
  "publisher": "O'Reilly Media",
  "contributors": ["John Smith", "ACME CORP."]
}
```

## Response (201 Created)

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "library_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Example Book Title",
  "author": "Jane Doe",
  "isbn": "978-0-123456-78-9",
  "description": "A great book about technology",
  "file_path": "/library/books/example.epub",
  "file_size": 1048576,
  "mime_type": "application/epub+zip",
  "series": "Tech Series",
  "series_number": 1,
  "tags": ["Science-Fiction", "Technology", "ACME CORP."],
  "tags_search": ["science fiction", "technology", "acme corp"],
  "publisher": "O'Reilly Media",
  "contributors": ["John Smith", "ACME CORP."],
  "contributors_search": ["john smith", "acme corp"],
  "created_at": "2026-01-31T10:00:00Z",
  "updated_at": "2026-01-31T10:00:00Z"
}
```

## Error Responses

| Code | Description                                    |
| ---- | ---------------------------------------------- |
| 400  | Invalid request data OR library has no folders |
| 401  | Invalid or expired token                       |
| 403  | User is not an admin                           |
| 404  | Library not found                              |

### 400 - Library Has No Folders

When attempting to create a media item in a library that has no folders configured:

```json
{
  "error": "Cannot add media items to a library with no folders. Please add at least one folder to the library first."
}
```

**Solution**: Add a folder to the library first:

```bash
POST /api/libraries/{library_id}/folders
{
  "folder_path": "/path/to/library/folder"
}
```
