info:
  name: Sync Progress - With Highlights and Notes
  type: http
  seq: 4

http:
  method: POST
  url: '{{base_url}}/api/sync/koreader/progress'
  auth: inherit
  headers:
    - key: Content-Type
      value: application/json
  body:
    type: json
    json:
      library_id: optional-library-uuid
      books:
        - uuid: book-uuid-here
          title: Book Title
          authors:
            - Author Name
          progress: 0.6
          percentage: 0.6
          last_read: '2026-01-30T20:00:00Z'
          highlights:
            - datetime: '2026-01-30T19:50:00Z'
              text: Important passage
              chapter: 4
              pos0: 'epubcfi(/6/4/2:20)'
              pos1: 'epubcfi(/6/4/2:30)'
              page_start: 78
              page_end: 79
          notes:
            - datetime: '2026-01-30T19:52:00Z'
              text: My note about this chapter
              chapter: 4

docs: |-
  ## Sync Progress with Highlights and Notes

  Synchronizes reading progress with separate highlights and notes arrays.

  **Method:** POST

  **Endpoint:** /api/sync/koreader/progress

  **Authentication:** Bearer token

  **Request Body:**
  - `library_id` (string, optional): Library UUID
  - `books` (array): Books with progress and annotations
    - `uuid`, `title`, `authors`, `progress`, `percentage`, `last_read`
    - `highlights` (array): Text highlights
      - `datetime` (string): Creation timestamp
      - `text` (string): Highlighted text content
      - `chapter` (integer): Chapter number
      - `pos0` (string): EPUB CFI start
      - `pos1` (string): EPUB CFI end
      - `page_start` (integer): Start page
      - `page_end` (integer): End page
      - `color` (string, optional): Highlight color
    - `notes` (array): Notes
      - `datetime` (string): Creation timestamp
      - `text` (string): Note content
      - `chapter` (integer): Chapter number
      - `pos0` (string, optional): Related position

  **Response:**
  - `progress_synced` (boolean): Progress sync status
  - `highlights_synced` (integer): Highlights synced
  - `notes_synced` (integer): Notes synced
  - `conflicts_resolved` (integer): Conflict count
  - `timestamp` (string): Sync timestamp

  **KOReader Annotation Model:**
  - **Separate arrays**: Highlights and notes stored separately
  - **Linked**: Notes can reference highlights
  - **Rich metadata**: Timestamps, positions, page numbers
  - **Flexible**: Supports complex annotations

  **Highlight Features:**
  - Multi-color highlighting (via plugins)
  - Precise text selection with EPUB CFI
  - Page range tracking
  - Chapter references
  - Timestamps for sorting
  - Full text preserved

  **Note Features:**
  - Free-form text notes
  - Can be standalone or attached
  - Chapter-based organization
  - Timestamped
  - Longer form than highlights
  - Support for markdown (some versions)

  **Color Support (via plugins):**
  - Yellow: Default highlight
  - Green: Important passages
  - Blue: Key concepts
  - Red: Critical information
  - Orange: Interesting quotes
  - Custom colors available

  **Sync Advantages:**
  - Separation allows granular control
  - Highlights sync without notes
  - Notes sync independently
  - Better conflict resolution
  - Efficient for large annotation sets

  **Use Cases:**
  - Academic research
  - Study groups
  - Content analysis
  - Personal knowledge management
  - Sharing insights