--- method: POST path: /api/media-items auth: jwt+admin area: media-items --- # 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/list_libraries.md) 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 example-request { "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 example-response { "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", "abridged": null, "added_by_admin_id": null, "age_rating": null, "alternate_info": null, "archived_at": null, "asin": null, "audio_metadata": null, "authors": null, "authors_search": null, "chapter_count": null, "chapter_metadata": null, "community_rating": null, "copyright_year": null, "cover_image_path": null, "date_published": null, "edition": null, "entitlement_id": null, "explicit": null, "file_sha256": null, "format_group": null, "format_mimetype": null, "genre": null, "goodreads_id": null, "google_books_id": null, "has_fixed_layout": null, "hash_confidence": null, "imported_at": null, "imprint": null, "is_black_and_white": null, "is_reflowable": null, "kobo_content_id": null, "kobo_metadata": null, "language": null, "library_type_name": null, "manga_type": null, "metadata_notes": null, "metadata_overrides": null, "missing_scan_count": null, "narrators": null, "narrators_search": null, "openlibrary_id": null, "opf_identifier": null, "opf_uuid": null, "page_count": null, "publishers": null, "publishers_search": null, "reading_direction": null, "revision_number": null, "scan_information": null, "series_count": null, "story_arc": null, "subtitle": null, "summary": null, "total_characters": null, "volume": null, "web_url": null } ``` ## 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" } ```