info:
  name: Sync Single Bookmark
  type: http
  seq: 5

http:
  method: POST
  url: '{{base_url}}/api/sync/kobo/bookmark'
  auth: inherit
  headers:
    - key: Content-Type
      value: application/json
    - key: x-kobo-device
      value: '{"DeviceId":"{{kobo_device_id}}","Model":"Kobo Clara"}'
  body:
    type: json
    json:
      ContentId: book-uuid
      BookmarkText: Bookmarked passage
      BookmarkType: annotation
      BookmarkTitle: Chapter 3

docs: |-
  ## Sync Single Bookmark

  Synchronizes an individual bookmark/highlight from Kobo device.

  **Method:** POST

  **Endpoint:** /api/sync/kobo/bookmark

  **Authentication:** Bearer token

  **Headers:**
  - `Authorization`: Bearer {{kobo_device_token}}
  - `x-kobo-device`: Device information JSON

  **Request Body:**
  - `ContentId` (string): Book UUID
  - `BookmarkText` (string): Highlighted text or bookmark description
  - `BookmarkType` (string): Type of bookmark
    - `annotation`: Highlighted text passage
    - `note`: Personal note
    - `bookmark`: Location marker
  - `BookmarkTitle` (string): Reference title (e.g., chapter name)
  - `ChapterID` (string, optional): Chapter identifier
  - `DateCreated` (string, optional): ISO 8601 timestamp
  - `highlight_color` (string, optional): Color name (yellow, green, blue, pink, orange)

  **Response:**
  - `id` (string): Server bookmark ID
  - `ContentId` (string): Associated book UUID
  - `status` (string): `created`, `updated`, `skipped` (duplicate)
  - `timestamp` (string): Server timestamp
  - `url` (string): API URL to retrieve bookmark

  **Status Codes:**
  - 201: Bookmark created
  - 200: Bookmark updated (duplicate found)
  - 409: Duplicate bookmark (unchanged)
  - 401: Unauthorized
  - 400: Invalid bookmark data

  **Single Bookmark Sync vs Batch:**
  - **Single bookmark endpoint:** Real-time, immediate sync
  - **Batch markup endpoint:** Deferred, periodic sync
  - Use single when user explicitly creates highlight
  - Use batch for periodic background sync

  **Kobo Trigger:**
  - User highlights text → immediate single sync
  - User adds note → immediate single sync
  - Device goes online → batch sync of all changes

  **Duplicate Detection:**
  - Same ContentId + similar BookmarkText + same location
  - Updates existing if text modified
  - Skips if identical bookmark exists
  - Preserves creation date of original

  **Use Cases:**
  - Real-time highlight sync
  - Instant note backup
  - Immediate annotation sharing
  - Quick single annotation update
  - Testing annotation sync

  **Notes:**
  - Much faster than full markup sync
  - Lower bandwidth usage
  - Ideal for intermittent connectivity
  - Can be called multiple times safely