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.
122 lines
2.8 KiB
Markdown
122 lines
2.8 KiB
Markdown
# 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
|
|
|
|
```json
|
|
{
|
|
"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)
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```http
|
|
GET /api/sync/koreader/metadata/book-uuid
|
|
Authorization: Bearer device-token
|
|
```
|
|
|
|
### Response (200 OK)
|
|
|
|
```json
|
|
{
|
|
"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"
|
|
}
|
|
```
|