# 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"
}
```
