john-okeefe
d43bd9526b
- sync_api.md - Comprehensive WebSocket API guide Covers: - Connection and authentication (JWT + device) - Client→Server messages (subscribe, ping) - Server→Client messages (progress, conflicts, scan status, etc.) - Message formats with examples - Connection lifecycle - Topics: progress, conflicts, scanner, devices, queue - JavaScript usage example with reconnection - Best practices for heartbeat and error handling Documents bidirectional real-time sync API
72 lines
1.7 KiB
Markdown
72 lines
1.7 KiB
Markdown
# Sync Bookmarks
|
|
|
|
Sync bookmarks from KOReader device.
|
|
|
|
**Endpoint**: `POST /api/sync/koreader/bookmarks`
|
|
**Auth**: Required (Device authentication)
|
|
|
|
## Device Authentication
|
|
|
|
This endpoint requires device authentication (not user JWT). Devices authenticate using their device credentials.
|
|
|
|
## Request Body
|
|
|
|
| Field | Type | Required | Description |
|
|
|--------|------|-----------|-------------|
|
|
| device_id | string (UUID) | Yes | Device UUID |
|
|
| bookmarks | array | Yes | Array of bookmark objects |
|
|
|
|
### Bookmark Object
|
|
|
|
| Field | Type | Required | Description |
|
|
|--------|------|-----------|-------------|
|
|
| book | string | Yes | Book identifier |
|
|
| chapter | string | No | Chapter title |
|
|
| page | integer | No | Page number |
|
|
| position | float | Yes | Position in document (0-1) |
|
|
| notes | string | No | Bookmark notes |
|
|
| highlighted_text | string | No | Highlighted text |
|
|
| time | string | Yes | ISO 8601 timestamp |
|
|
| created_at | string | Yes | ISO 8601 timestamp |
|
|
|
|
### Example Request
|
|
|
|
```json
|
|
{
|
|
"device_id": "550e8400-e29b-41d4-a716-446655440000",
|
|
"bookmarks": [
|
|
{
|
|
"book": "book.epub",
|
|
"chapter": "Chapter 1",
|
|
"page": 25,
|
|
"position": 0.125,
|
|
"notes": "Important section",
|
|
"highlighted_text": "Text to remember",
|
|
"time": "2026-02-08T10:00:00Z",
|
|
"created_at": "2026-02-08T10:00:00Z"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Response (200 OK)
|
|
|
|
```json
|
|
{
|
|
"message": "Bookmarks synced successfully",
|
|
"synced_count": 1
|
|
}
|
|
```
|
|
|
|
## Error Responses
|
|
|
|
| Code | Description |
|
|
|------|-------------|
|
|
| 401 | Device authentication failed |
|
|
| 400 | Invalid request data |
|
|
| 404 | Device not found |
|
|
|
|
## Try It Out
|
|
|
|
<!-- API Explorer will be inserted here in Phase 3 -->
|