Files

T

john-okeefe b44e4e4709 docs: remove Phase X placeholders from API documentation

Clean up API documentation files by removing Phase X references:

Remove 'API Explorer will be inserted here in Phase X' placeholders from:
- 70+ API endpoint documentation files
- Authentication endpoints (login, logout, register, refresh)
- User endpoints (profile, settings, password)
- Device endpoints (registration, sync, shelves)
- Library endpoints (CRUD, folders, visibility)
- Media endpoints (items, progress, highlights, notes)
- Admin endpoints (users, analytics)
- Sync endpoints (Kobo, KOReader)
- OPDS endpoints
- Scanner endpoints
- Queue endpoints

These placeholders were from planning documents and have no meaning
to API consumers. The documentation is now clean and ready for use.

2026-02-13 21:50:44 -05:00

3.6 KiB

Raw Blame History

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:

Create a library: POST /api/libraries
Add folder(s) to the library: POST /api/libraries/{library_id}/folders
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"
}

3.6 KiB Raw Blame History