fix(docs): Work Order 2 — correct stale paths (11 docs + 3 Bruno)

Fix all wrong-path artifacts identified by the audit:
- Kobo sync endpoints (init/bookmark/markup/sync-from-server/analytics): add
  missing :token device segment (6 doc files incl. kobo-protocol.md)
- Highlights/notes update+delete: add missing /:id media-item prefix
- media-items/download_media_item.md: removed (static /uploads route, not an
  API endpoint; info about the file route is recoverable from OPDS docs)
- Bruno: /libraries/visible -> /visibility, /collections/books missing id,
  /audio/0 -> track_index
- operations/troubleshooting.md: same /libraries/visible -> /visibility fix
- media-items/get_audio_track.md + get_audio_chapters.md: /audio/0 examples fixed
- Deleted monolithic docs/developer/api-reference.md (duplicate of split docs)
- Fixed 4 stale entries in docs/developer/api/api-reference.md (split index)

Audit re-run: orphan docs 0, orphan Bruno 6 (all scenario files with literal IDs).
This commit is contained in:
John O'Keefe committed 2026-10-24 14:44:19 -04:00
1 parent cc893f758e
commit 50282895f5
19 files changed
+29 -1831

No files matched your search

@@ -1,48 +0,0 @@
# 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).
@@ -23,7 +23,7 @@ which file model produced them.
"tracks": [
{
"index": 0,
"url": "/api/media-items/{id}/audio/0",
"url": "/api/media-items/{id}/audio/{trackIndex}",
"title": "01 First",
"path": "Author/Title/01 First.mp3",
"start": 0.0,
@@ -40,5 +40,5 @@ answers **403** on every track (same gate as the download endpoint).
```bash
curl -H "Authorization: Bearer $TOKEN" \
-H "Range: bytes=0-1023" \
"http://localhost:8765/api/media-items/550e8400-.../audio/0"
"http://localhost:8765/api/media-items/550e8400-.../audio/{track_index}"
```