bookhoard/docs/developer/api/media-items/create_media_item.md

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 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

{
  "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)

{
  "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:

{
  "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:

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

Try It Out