john-okeefe
b44e4e4709
Clean up API documentation files by removing Phase X references: Remove 'API Explorer will be inserted here in Phase X' placeholders from: - 70+ API endpoint documentation files - Authentication endpoints (login, logout, register, refresh) - User endpoints (profile, settings, password) - Device endpoints (registration, sync, shelves) - Library endpoints (CRUD, folders, visibility) - Media endpoints (items, progress, highlights, notes) - Admin endpoints (users, analytics) - Sync endpoints (Kobo, KOReader) - OPDS endpoints - Scanner endpoints - Queue endpoints These placeholders were from planning documents and have no meaning to API consumers. The documentation is now clean and ready for use.
2.8 KiB
2.8 KiB
KOReader Sync Protocol
KOReader uses a custom JSON-based sync protocol.
KOReader Progress Sync
Endpoint: POST /api/sync/koreader/progress
Auth: Device token required
Content-Type: application/json
Request Headers
| Header | Type | Required | Description |
|---|---|---|---|
| Authorization | string | Yes | Bearer device token |
| Content-Type | string | Yes | application/json |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| library_id | string | No | Library UUID |
| books | array | Yes | Array of book sync data |
| books[].uuid | string | Yes | Book UUID |
| books[].title | string | Yes | Book title |
| books[].authors | array | Yes | Array of author names |
| books[].progress | float | Yes | Progress percentage (0-1) |
| books[].percentage | float | Yes | Progress percentage (0-1) |
| books[].last_read | string | Yes | ISO 8601 timestamp |
| books[].chapter | integer | No | Current chapter |
| books[].epubcfi | string | No | EPUB CFI location |
| books[].character | integer | No | Character offset |
| books[].bookmarks | array | No | Array of bookmarks/highlights |
Example Request
{
"library_id": "optional-uuid",
"books": [
{
"uuid": "book-uuid",
"title": "Book Title",
"authors": ["Author Name"],
"progress": 0.45,
"percentage": 0.45,
"last_read": "2026-01-30T20:00:00Z",
"chapter": 3,
"epubcfi": "epubcfi(/6/4/2:15)",
"character": 15432,
"bookmarks": [
{
"chapter": 3,
"datetime": "2026-01-30T19:55:00Z",
"notes": "highlighted text",
"pos0": "epubcfi(/6/4/2:15)",
"pos1": "epubcfi(/6/4/2:20)",
"page": 45,
"text": "highlighted text excerpt",
"type": "highlight"
}
],
"highlights": [],
"notes": []
}
]
}
Response (202 Accepted)
{
"sync_status": "accepted",
"books_synced": 1,
"conflicts": [
{
"book_uuid": "book-uuid",
"conflict_type": "progress_mismatch",
"device_progress": 0.45,
"server_progress": 0.42,
"resolution": "device_wins"
}
]
}
KOReader Metadata Fetch
Endpoint: GET /api/sync/koreader/metadata/{book_uuid}
Auth: Device token required
Example Request
GET /api/sync/koreader/metadata/book-uuid
Authorization: Bearer device-token
Response (200 OK)
{
"uuid": "book-uuid",
"title": "Book Title",
"authors": ["Author Name"],
"progress": {
"percentage": 0.42,
"character": 15432,
"epubcfi": "epubcfi(/6/4/2:15)",
"chapter": 3,
"chapter_progress": 0.234
},
"annotations": {
"highlights": [...],
"notes": [...],
"bookmarks": [...]
},
"last_sync": "2026-01-30T20:00:00Z"
}