Files

T

john-okeefe c437528522 docs(api): add new endpoint documentation

- Add create_media_item.md for media item creation API

- Add delete_rating.md for rating deletion endpoint

- Add update_rating.md for rating update endpoint

2026-02-08 13:33:09 -05:00

3.0 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

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
401	Invalid or expired token
403	User is not an admin
404	Library not found

3.0 KiB Raw Blame History