Files

T

john-okeefe 4d321528b2 docs: update comprehensive API documentation and project guides

This commit updates all documentation files throughout the project:

- Updated IMPLEMENTATION_PLAN.md with new implementation details
- Updated PROJECT_GUIDELINES.md with coding standards and practices
- Updated README.md with current project information
- Updated SCREENSHOT_AUTOMATION.md with new automation details
- Added TEST_DATA.md with test fixtures data
- Updated cover_image_serving_plan.md with static URL patterns

Documentation API updates:
- Updated API reference documentation for all endpoints including:
  - Authentication (login, logout, register, refresh_token)
  - Book matching (auto_link, bulk_link, link_book, search)
  - Collections (CRUD operations, shelf mappings, auto-assign rules)
  - Conflicts (bulk operations, resolve/dismiss)
  - Devices (registration, approval, shelf management)
  - Highlights (create, update, delete, get)
  - Kobo sync (bookmark, markup, initialization, sync)
  - KOReader sync (library, metadata, bookmarks, progress)
  - Libraries (CRUD, folders, media items, stats)
  - Media items (bulk operations, CRUD)
  - Notes (CRUD operations)
  - OPDS (acquisition, feeds, publication)
  - Progress (reading progress tracking)
  - Queue (device queue management)
  - Ratings (star ratings)
  - Scanner (watch mode, scan operations)
  - Sync protocols (Kobo, KOReader)
  - Users (profile, password, admin operations)
  - WebSocket protocols

- Updated user guides (admin, dashboard, settings, sync)
- Updated device setup guides (Kobo, KOReader)
- Updated developer guides (testing, contributing, operations)
- Updated scripts/README.md

2026-02-27 17:06:22 -05:00

4.5 KiB

Raw Permalink 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"
}

4.5 KiB Raw Permalink Blame History