info:
  name: Sync Highlights
  type: http
  seq: 6

http:
  method: POST
  url: '{{base_url}}/api/sync/koreader/highlights'
  auth: inherit
  headers:
    - key: Content-Type
      value: application/json
  body:
    type: json
    json:
      library_id: optional-library-uuid
      books:
        - uuid: book-uuid
          highlights:
            - datetime: '2026-01-30T19:50:00Z'
              text: Important quote from book
              chapter: 4
              pos0: 'epubcfi(/6/4/2:20)'
              pos1: 'epubcfi(/6/4/2:30)'
              page_start: 78
              page_end: 79

docs: |-
  ## Sync KOReader Highlights

  Synchronizes text highlights separately from other annotations.

  **Method:** POST

  **Endpoint:** /api/sync/koreader/highlights

  **Authentication:** Bearer token

  **Request Body:**
  - `library_id` (string, optional): Library UUID
  - `books` (array): Books with highlights
    - `uuid` (string): Book UUID
    - `highlights` (array): Highlight items
      - `datetime` (string): Creation timestamp
      - `text` (string): Highlighted text content
      - `chapter` (integer): Chapter number
      - `pos0` (string): EPUB CFI start position
      - `pos1` (string): EPUB CFI end position
      - `page_start` (integer): Start page
      - `page_end` (integer): End page
      - `color` (string, optional): Color name or hex
      - `note` (string, optional): Attached note

  **Response:**
  - `synced` (integer): Highlights synced
  - `duplicates_skipped` (integer): Duplicates found
  - `with_notes` (integer): Highlights that have notes attached
  - `timestamp` (string): Sync timestamp

  **KOReader Highlight Features:**
  - Precise text selection (EPUB CFI)
  - Custom color support (via plugins)
  - Multi-page highlights
  - Chapter references
  - Timestamps for sorting
  - Attached notes support
  - Full text preservation

  **Highlight Colors (via plugins):**
  - Yellow (default): General highlighting
  - Green: Important concepts
  - Blue: Key information
  - Red/pink: Critical content
  - Orange: Interesting quotes
  - Custom RGB colors available

  **EPUB CFI Advantages:**
  - Precise start/end positions
  - Works across font size changes
  - Survives text reflow
  - Device-independent
  - Standardized format

  **Dedicated Highlight Endpoint:**
  - **Separate from progress**: Sync highlights independently
  - **Smaller payload**: Just highlights, no progress
  - **More frequent**: Can sync highlights immediately
  - **Focused**: Single-purpose endpoint

  **Sync Behavior:**
  - Exact text matching for duplicates
  - Position-based conflict resolution
  - Color preservation across devices
  - Note attachments preserved
  - Order maintained by position

  **KOReader Device Features:**
  - Created via long-press or selection
  - Color picker available
  - Can add notes immediately
  - Shows in "Highlights" panel
  - Exportable to Evernote, etc.
  - Searchable by content

  **Use Cases:**
  - Study and research
  - Content curation
  - Quote collection
  - Academic work
  - Sharing insights