Files

T

john-okeefe d43bd9526b docs(api): add WebSocket real-time sync API documentation

- 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

2026-02-08 12:38:50 -05:00

1.2 KiB

Raw Blame History

Get Metadata

Get metadata for a book from KOReader device.

Endpoint: GET /api/sync/koreader/metadata/:uuid Auth: Required (Device authentication)

Path Parameters

Parameter	Type	Required	Description
uuid	string (UUID)	Yes	Book UUID

Device Authentication

This endpoint requires device authentication (not user JWT). Devices authenticate using their device credentials.

Request Headers

Header	Type	Required	Description
X-Device-ID	string	Yes	Device UUID
X-Device-Key	string	Yes	Device authentication key

Example Request

GET /api/sync/koreader/metadata/550e8400-e29b-41d4-a716-446655440000
X-Device-ID: 550e8400-e29b-41d4-a716-446655440000
X-Device-Key: device-auth-key

Response (200 OK)

{
  "id": "uuid",
  "title": "Book Title",
  "authors": ["Author Name"],
  "path": "/path/to/book.epub",
  "file_size": 1234567,
  "modified_at": "2026-02-08T10:00:00Z"
}

Error Responses

Code	Description
401	Device authentication failed
404	Book or device not found

1.2 KiB Raw Blame History