info:
  name: Sync Notes
  type: http
  seq: 7

http:
  method: POST
  url: '{{base_url}}/api/sync/koreader/notes'
  auth: inherit
  headers:
    - key: Content-Type
      value: application/json
  body:
    type: json
    json:
      library_id: optional-library-uuid
      books:
        - uuid: book-uuid
          notes:
            - datetime: '2026-01-30T19:52:00Z'
              text: My personal note about this chapter
              chapter: 4

docs: |-
  ## Sync KOReader Notes

  Synchronizes user notes separately from highlights and bookmarks.

  **Method:** POST

  **Endpoint:** /api/sync/koreader/notes

  **Authentication:** Bearer token

  **Request Body:**
  - `library_id` (string, optional): Library UUID
  - `books` (array): Books with notes
    - `uuid` (string): Book UUID
    - `notes` (array): Note items
      - `datetime` (string): Creation/modification timestamp
      - `text` (string): Note content
      - `chapter` (integer): Chapter number
      - `pos0` (string, optional): Related EPUB CFI position
      - `page` (integer, optional): Page number
      - `highlighted_text` (string, optional): Related highlight

  **Response:**
  - `synced` (integer): Notes synced
  - `duplicates_skipped` (integer): Duplicate notes found
  - `attached_to_highlights` (integer): Notes linked to highlights
  - `timestamp` (string): Sync timestamp

  **KOReader Note Features:**
  - Free-form text notes
  - Can be standalone or attached to highlights
  - Chapter-based organization
  - Timestamped for sorting
  - Markdown support (some versions)
  - Longer form content
  - No character limit

  **Note Types:**
  - **Standalone notes**: Independent notes about chapter/section
  - **Attached notes**: Notes attached to specific highlights
  - **Chapter notes**: Notes about entire chapter
  - **Book notes**: General notes about the book

  **Dedicated Notes Endpoint:**
  - **Separate sync**: Notes sync independently
  - **Flexible**: Not tied to highlights
  - **Efficient**: Smaller, focused payload
  - **Immediate**: Can sync right after note creation

  **Attached Notes:**
  - Linked to specific highlight
  - Shares highlight's position
  - Shown together with highlight
  - Deleted when highlight deleted (optional)
  - Color matches highlight

  **Sync Behavior:**
  - Text-based duplicate detection
  - Time-based conflict resolution
  - Chapter organization preserved
  - Markdown formatting preserved
  - Attachment links maintained

  **KOReader Device Integration:**
  - Created via "Add note" option
  - Edited in note editor
  - Shown in "Notes" panel
  - Can be organized by chapter
  - Export functionality available
  - Search support

  **Advanced Features:**
  - **Markdown**: Bold, italic, lists (some versions)
  - **Tags**: User-defined tags (via plugins)
  - **Links**: Internal/external links
  - **Formatting**: Rich text in newer versions

  **Use Cases:**
  - Study notes
  - Personal reflections
  - Academic annotations
  - Research insights
  - Book club discussion prep
  - Knowledge management