# Kobo Sync Protocol

> **Status: Coming Soon** — Native Kobo sync is implemented server-side but not yet supported on real devices. These endpoints are under active development and may change. Until then, KOReader (which runs on Kobo hardware) is fully supported.

Kobo uses a proprietary sync protocol with JSON payloads.

## Kobo Markup Sync

**Endpoint**: `POST /api/sync/kobo/markup`
**Auth**: Device token required
**Content-Type**: `application/json`

### Request Headers

| Header        | Type   | Required | Description         |
| ------------- | ------ | -------- | ------------------- |
| Authorization | string | Yes      | Bearer device token |
| x-kobo-device | string | Yes      | JSON device info    |
| Content-Type  | string | Yes      | application/json    |

### Request Body

| Field                              | Type    | Required | Description                    |
| ---------------------------------- | ------- | -------- | ------------------------------ |
| ReadingSync                        | array   | No       | Array of reading progress data |
| ReadingSync[].ContentId            | string  | Yes      | Book UUID                      |
| ReadingSync[].PercentRead          | float   | Yes      | Progress percentage (0-100)    |
| ReadingSync[].EntitlementId        | string  | Yes      | Kobo entitlement ID            |
| ReadingSync[].RemainingTimeMinutes | integer | No       | Estimated remaining time       |
| ReadingSync[].LastModified         | string  | Yes      | ISO 8601 timestamp             |
| BookmarkSync                       | array   | No       | Array of bookmarks/highlights  |

### Example Request

```http
POST /api/sync/kobo/markup
Authorization: Bearer device-token
x-kobo-device: {"DeviceId":"device-id","Model":"Kobo Clara"}
Content-Type: application/json

{
  "ReadingSync": [
    {
      "ContentId": "book-uuid",
      "PercentRead": 45.6,
      "EntitlementId": "entitlement-id",
      "RemainingTimeMinutes": 120,
      "LastModified": "2026-01-30T20:00:00Z"
    }
  ],
  "BookmarkSync": [
    {
      "ContentId": "book-uuid",
      "BookmarkText": "highlighted text",
      "BookmarkType": "annotation",
      "BookmarkTitle": "Chapter 3"
    }
  ]
}
```

### Response (200 OK)

```json
{
  "Status": "Success",
  "MarkupsSynced": 5,
  "BookmarksSynced": 3
}
```

## Kobo Library Fetch

**Endpoint**: `GET /api/sync/kobo/library`
**Auth**: Device token required

### Example Request

```http
GET /api/sync/kobo/library
Authorization: Bearer device-token
```

### Response (200 OK)

```json
{
  "library_sync": [
    {
      "ContentId": "book-uuid",
      "ContentType": "6",
      "Title": "Book Title",
      "Author": "Author Name",
      "PercentRead": 42.3,
      "PagesRemaining": 115,
      "BookmarkCount": 3,
      "LastModified": "2026-01-30T20:00:00Z"
    }
  ]
}
```