info:
  name: Sync Bookmarks
  type: http
  seq: 5

http:
  method: POST
  url: '{{base_url}}/api/sync/koreader/bookmarks'
  auth: inherit
  headers:
    - key: Content-Type
      value: application/json
  body:
    type: json
    json:
      library_id: optional-library-uuid
      books:
        - uuid: book-uuid
          bookmarks:
            - chapter: 3
              datetime: '2026-01-30T19:55:00Z'
              notes: Marked this chapter as important
              pos0: 'epubcfi(/6/4/2:15)'
              pos1: 'epubcfi(/6/4/2:20)'
              page: 45
              text: Important passage
              type: bookmark

docs: |-
  ## Sync KOReader Bookmarks

  Synchronizes bookmarks separately from progress for KOReader.

  **Method:** POST

  **Endpoint:** /api/sync/koreader/bookmarks

  **Authentication:** Bearer token

  **Request Body:**
  - `library_id` (string, optional): Library UUID
  - `books` (array): Books with bookmarks
    - `uuid` (string): Book UUID
    - `bookmarks` (array): Bookmark items
      - `chapter` (integer): Chapter number
      - `datetime` (string): ISO 8601 timestamp
      - `notes` (string): Bookmark description
      - `pos0` (string): EPUB CFI start position
      - `pos1` (string): EPUB CFI end position
      - `page` (integer): Page number
      - `text` (string): Displayed text
      - `type` (string): `bookmark`, `highlight`, or `note`

  **Response:**
  - `synced` (integer): Number of bookmarks synced
  - `duplicates_skipped` (integer): Duplicate bookmarks skipped
  - `results` (array): Per-bookmark results
  - `timestamp` (string): Sync timestamp

  **Status Codes:**
  - 200: Success
  - 401: Unauthorized
  - 400: Invalid data

  **Dedicated Bookmark Endpoint:**
  - **Purpose**: Sync bookmarks independently
  - **Use case**: More frequent bookmark updates
  - **Advantage**: Separate from progress sync
  - **Efficiency**: Smaller payloads

  **KOReader Bookmark Features:**
  - Chapter-based organization
  - Quick navigation markers
  - Hierarchical bookmarks (via plugins)
  - Custom bookmark titles
  - Date/time tracking
  - EPUB CFI precision

  **Bookmark Types in KOReader:**
  - **Location bookmarks**: Quick navigation points
  - **Chapter marks**: Auto-generated chapter markers
  - **Progress bookmarks**: Last read positions
  - **Custom bookmarks**: User-created markers
  - **Search bookmarks**: Saved search results

  **Sync Behavior:**
  - Duplicate detection by position + text
  - Most recent wins on conflicts
  - Chapter order preserved
  - Auto-generated vs manual bookmarks differentiated
  - Merge with existing bookmarks

  **KOReader Device Integration:**
  - Created via "Add bookmark" menu
  - Shown in "Bookmarks" panel
  - Quick access via "Go to bookmark"
  - Exportable to JSON
  - Can be edited/deleted

  **Use Cases:**
  - Quick navigation aids
  - Chapter markers
  - Important passages
  - Reading progress points
  - Study session markers