john-okeefe
44735554f7
The documented GET /api/media-items/:uuid/download is not registered
anywhere - MediaHandler.DownloadBook exists but no route mounts it.
Book files (and covers) are actually served by the JWT-authenticated
GET /uploads/library-{id}/{path} route that the web reader uses.
Rewrite the download doc around the real file route (URL construction
from the item's library_id and relative file_path, MIME/Cache headers,
error codes), note the dead handler so nobody relies on the phantom
endpoint, and correct the API reference index. Mention the OPDS device
route as the conversion-capable alternative.
1.9 KiB
1.9 KiB
Download Media Item
Download a media item file (EPUB, PDF, etc.) from the Bookhoard server.
Book files are served by the authenticated file route, the same one the web reader uses. Build the URL from the media item's library_id and relative file_path (both returned by the media item list/get endpoints):
Endpoint: GET /uploads/library-{library_id}/{file_path}
Auth: Required (JWT - Bearer header or session cookie)
The file_path segments are URL-escaped individually; slashes are preserved. cover_image_path uses the same route.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| library_id | string | Yes | Library UUID (the item's library) |
| file_path | string | Yes | The item's relative file_path |
Response
Success (200 OK): Binary file data
Response Headers:
Content-Type: MIME type by file extension (application/epub+zip,application/pdf, …;application/octet-streamfallback)Cache-Control:public, max-age=86400
Error Responses
| Code | Description |
|---|---|
| 400 | Invalid library ID or path |
| 401 | Missing/invalid token |
| 404 | File not found on disk |
Example
curl -O -H "Authorization: Bearer $TOKEN" \
"http://localhost:8765/uploads/library/550e8400-.../books/1984.epub"
(URL shape: /uploads/library-{uuid}/{escaped-relative-path}.)
Notes
- Do not rely on
GET /api/media-items/:id/download— it appears in older docs but is not registered;MediaHandler.DownloadBookexists as dead code. Use the file route above. - OPDS-capable devices may alternatively use the device-authenticated
GET /opds/devices/{deviceId}/download/{bookId}, which supports on-the-fly format conversion (epub, kepub, pdf, cbz).