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.
49 lines
1.9 KiB
Markdown
49 lines
1.9 KiB
Markdown
# 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-stream` fallback)
|
|
- `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
|
|
|
|
```bash
|
|
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.DownloadBook` exists 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).
|