refactor(bruno): reorganize file structure from bruno-yaml to flat bruno directory

- Move all files from bruno-yaml/* to bruno/* - Maintains existing directory structure within categories - Updates bruno/user/auth files with OAuth2 refresh token flow - Updates bruno/user/profile files for user profile management - Adds bruno/dashboard/ directory with dashboard API tests - Preserves all existing test scenarios and OpenCollection YAML format - No functional changes - file reorganization only
2026-02-17 20:22:21 -05:00
parent 96730d9475
commit f859b2714d
221 changed files with 0 additions and 0 deletions
@@ -0,0 +1,45 @@
+info:
+  name: Auto-Link Unlinked Books
+  type: http
+  seq: 1
+http:
+  method: POST
+  url: '{{base_url}}/sync/auto-link-books'
+  auth: inherit
+  body:
+    type: json
+    jsonBody: "{\n    \"confidence_threshold\": 0.8,\n    \"limit\": 50"
+  headers:
+  - key: Content-Type
+    value: application/json
+  - key: Authorization
+    value: Bearer {{authToken
+
+docs: |-
+  ## Auto-Link Unlinked Books
+  
+    Automatically links unlinked books to media items based on title and author matching with a configurable confidence threshold.
+  
+    **Method:** POST
+  
+    **Endpoint:** /sync/auto-link-books
+  
+    **Authentication:** Bearer token
+  
+    **Request Body:**
+    - `confidence_threshold` (number, optional): Minimum confidence score for auto-linking (0-1, default: 0.8)
+    - `limit` (number, optional): Maximum number of books to auto-link (default: 50)
+  
+    **Response:**
+    - `results` (array): Results for each auto-link attempt
+    - `total` (number): Total number of books processed
+    - `success` (number): Number of successful links
+    - `failed` (number): Number of failed links
+  
+    **Status Codes:**
+    - 200: Success
+    - 400: Invalid request data
+    - 401: Unauthorized
+    - 500: Internal server error
+  
+    **Note:** Higher confidence thresholds produce fewer but more accurate matches. Consider the tradeoff between automation and accuracy.
@@ -0,0 +1,47 @@
+info:
+  name: Bulk Link Unlinked Books
+  type: http
+  seq: 1
+http:
+  method: POST
+  url: '{{base_url}}/sync/bulk-link-books'
+  auth: inherit
+  body:
+    type: json
+    jsonBody: "{\n    \"links\": [\n      {\n        \"unlinked_book_id\": \"{{unlinkedBookId1"
+  headers:
+  - key: Content-Type
+    value: application/json
+  - key: Authorization
+    value: Bearer {{authToken
+
+docs: |-
+  ## Bulk Link Unlinked Books
+  
+    Links multiple unlinked books to media items in a single request.
+  
+    **Method:** POST
+  
+    **Endpoint:** /sync/bulk-link-books
+  
+    **Authentication:** Bearer token
+  
+    **Request Body:**
+    - `links` (array): Array of link objects
+      - `unlinked_book_id` (string): Unlinked book UUID
+      - `media_item_id` (string): Media item UUID to link to
+      - `confidence_score` (number): Match confidence (0-1)
+  
+    **Response:**
+    - `results` (array): Results for each link attempt
+    - `total` (number): Total number of links processed
+    - `success` (number): Number of successful links
+    - `failed` (number): Number of failed links
+  
+    **Status Codes:**
+    - 200: Success
+    - 400: Invalid request data
+    - 401: Unauthorized
+    - 500: Internal server error
+  
+    **Note:** Use this endpoint after reviewing suggestions from the Get Unlinked Book Suggestions endpoint.
@@ -0,0 +1,98 @@
+info:
+  name: Kobo Initialization
+  type: http
+  seq: 8
+
+http:
+  method: GET
+  url: '{{base_url}}/api/sync/kobo/v1/initialization'
+  auth: inherit
+
+docs: |-
+  ## Kobo Device Initialization
+
+  Initializes Kobo device sync session and returns device configuration.
+
+  **Method:** GET
+
+  **Endpoint:** /api/sync/kobo/v1/initialization
+
+  **Authentication:** Bearer token
+
+  **Query Parameters:**
+  - `Platform` (string, optional): Device platform (android, kobo)
+  - `FirmwareVersion` (string, optional): Firmware version string
+  - `Model` (string, optional): Device model name
+
+  **Response:**
+  - `device` (object): Device information
+    - `device_id` (string): Server device ID
+    - `approved` (boolean): Whether device is approved
+    - `sync_enabled` (boolean): Whether sync is active
+    - `last_sync` (string): Last successful sync timestamp
+  - `user` (object): User information
+    - `user_id` (string): User identifier
+    - `email` (string): User email (masked)
+    - `library_size` (integer): Number of books in library
+  - `sync_config` (object): Sync configuration
+    - `sync_interval_minutes` (integer): Recommended sync frequency
+    - `batch_size` (integer): Max items per batch
+    - `timeout_seconds` (integer): Request timeout
+    - `retry_count` (integer): Max retry attempts
+  - `features` (object): Available features
+    - `annotation_sync` (boolean): Annotation support
+    - `bookmark_sync` (boolean): Bookmark support
+    - `progress_sync` (boolean): Progress tracking
+    - `library_download` (boolean): Library access
+  - `endpoints` (object): API endpoint URLs
+    - `markup_sync` (string): Progress/annotation sync URL
+    - `bookmark_sync` (string): Bookmark sync URL
+    - `library` (string): Library access URL
+    - `sync_from_server` (string): Download sync URL
+  - `server_time` (string): Current server timestamp
+  - `version` (string): API version
+
+  **Status Codes:**
+  - 200: Success
+  - 401: Unauthorized (invalid token)
+  - 403: Forbidden (device not approved)
+  - 404: Device not found
+
+  **Initialization Flow:**
+  1. Device powers on or connects to network
+  2. Device calls initialization endpoint
+  3. Server returns configuration and capabilities
+  4. Device adjusts sync behavior based on config
+  5. Device begins sync operations
+
+  **Authentication Methods:**
+  This endpoint uses **Bearer token authentication** (token in Authorization header).
+  Alternative: Use `/sync/kobo/{token}/v1/initialization` with token in URL path.
+
+  **Configuration Caching:**
+  - Response cached on device for 24 hours
+  - Refreshed on device reboot
+  - Updated when sync settings change
+  - Can be force-refreshed via device settings
+
+  **Device Approval:**
+  - New devices: `approved: false`
+  - Pending devices see limited functionality
+  - Approval required for full sync
+  - User approves via web interface
+  - Re-initialization after approval
+
+  **Use Cases:**
+  - Device registration
+  - Daily device wakeup
+  - Post-approval initialization
+  - Configuration refresh
+  - Feature capability check
+  - Sync endpoint discovery
+
+  **Kobo Native Integration:**
+  - Called by Kobo Nickel UI
+  - Integrated with Kobo sync service
+  - Part of Kobo account setup
+  - Supports Kobo "Sync now" feature
+  - Enables Kobo library browsing
@@ -0,0 +1,53 @@
+info:
+  name: Sync from Bookhoard to Kobo
+  type: http
+  seq: 1
+http:
+  method: POST
+  url: '{{baseURL}}/api/sync/kobo/sync-from-server'
+  auth: inherit
+  body:
+    type: json
+    jsonBody: "[\n    {\n      \"ContentId\": \"{{bookUUID"
+  headers:
+  - key: Authorization
+    value: Bearer {{koboToken
+
+docs: |-
+  ## Sync from Bookhoard to Kobo
+  
+    Server-initiated sync pushing progress, bookmarks, and highlights from Bookhoard to Kobo device. Two-way sync endpoint.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/sync/kobo/sync-from-server
+  
+    **Authentication:** Bearer token with Kobo device identification
+  
+    **Headers:**
+    - `x-kobo-device` (string): JSON string containing Kobo device info
+      - `DeviceId`: Kobo device ID
+      - `Model`: Kobo device model
+      - `SerialNumber`: Kobo device serial number
+  
+    **Request Body:** Array of sync data objects
+    - `ContentId` (string): Book UUID
+    - `PercentRead` (number): Reading progress percentage (0-100)
+    - `LastModified` (string): ISO 8601 timestamp
+    - `Bookmarks` (array, optional): Array of bookmark objects
+      - `BookmarkId`: Unique bookmark ID
+      - `ContentId`: Book UUID
+      - `BookmarkText`: Bookmark text/note
+      - `BookmarkType`: Type (bookmark, annotation, etc.)
+      - `BookmarkTitle`: Bookmark title
+    - `Highlights` (array, optional): Array of highlight objects (same structure as bookmarks)
+  
+    **Response:**
+    - Sync result confirmation
+  
+    **Status Codes:**
+    - 200: Success
+    - 401: Unauthorized
+    - 500: Internal server error
+  
+    **Note:** Allows Bookhoard server to push updates to Kobo device, including reading progress, bookmarks, and highlights.
@@ -0,0 +1,106 @@
+info:
+  name: Sync Books from Server to Kobo
+  type: http
+  seq: 9
+
+http:
+  method: POST
+  url: '{{base_url}}/api/sync/kobo/sync-from-server'
+  auth: inherit
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    json:
+      force_sync: true
+      books:
+        - book-uuid-1
+        - book-uuid-2
+
+docs: |-
+  ## Sync Books from Server to Kobo
+
+  Pulls reading progress, annotations, and bookmarks from server to Kobo device.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/kobo/sync-from-server
+
+  **Authentication:** Bearer token
+
+  **Request Body:**
+  - `force_sync` (boolean): Force full sync (ignore last sync time)
+  - `books` (array, optional): List of book UUIDs to sync
+    - If empty, syncs all books with server data
+    - If specified, only syncs listed books
+  - `sync_options` (object, optional):
+    - `since_date` (string): ISO 8601 timestamp for incremental sync
+    - `include_annotations` (boolean): Include highlights/notes
+    - `include_progress` (boolean): Include reading progress
+    - `conflict_resolution` (string): `most_recent`, `server_wins`, `client_wins`
+
+  **Response:**
+  - `synced` (integer): Number of books synced
+  - `skipped` (integer): Books with no server changes
+  - `failed` (integer): Books that failed to sync
+  - `results` (array): Per-book sync results
+    - `book_id` (string): Book UUID
+    - `status` (string): `synced`, `skipped`, `failed`
+    - `progress_pulled` (boolean): Whether progress was downloaded
+    - `annotations_pulled` (integer): Number of annotations downloaded
+    - `error` (string, optional): Error message if failed
+  - `server_timestamp` (string): Server timestamp of sync
+
+  **Status Codes:**
+  - 200: Sync completed
+  - 207: Multi-status (some succeeded, some failed)
+  - 401: Unauthorized
+  - 400: Invalid request
+
+  **Sync Direction:**
+  - **Server → Device** (this endpoint)
+  - Device → Server: Use `/sync/kobo/markup` endpoint
+  - Bidirectional sync achieved by calling both
+
+  **Pull Sync Use Cases:**
+  - New device setup (download all progress)
+  - Device replacement (restore from server)
+  - Multi-device sync (pull changes from other devices)
+  - Conflict resolution (server wins)
+  - Manual "Download from server" operation
+
+  **Conflict Resolution:**
+  - `most_recent`: Latest timestamp wins (default)
+  - `server_wins`: Server data always used
+  - `client_wins`: Device data preserved
+  - Applied per-book, per-item
+
+  **Sync Optimization:**
+  - Incremental sync by default (since last sync)
+  - Force sync does full comparison
+  - Book-level batching (10 books per batch)
+  - Delta transfer (only changed items)
+  - Compression for large annotation sets
+
+  **Kobo Device Behavior:**
+  - Device updates local database
+  - Progress reflected in reading view
+  - Annotations appear in Notebook
+  - Bookmarks updated in navigation
+  - Conflict warnings shown to user
+  - Sync progress displayed on screen
+
+  **Performance:**
+  - Small sync (1-10 books): 2-5 seconds
+  - Medium sync (10-50 books): 5-15 seconds
+  - Large sync (50-200 books): 15-45 seconds
+  - Timeout: 120 seconds
+
+  **Use Cases:**
+  - Initial device sync
+  - After firmware update
+  - From another device's changes
+  - Manual sync request
+  - Conflict recovery
+  - Data restoration
@@ -0,0 +1,91 @@
+info:
+  name: Sync Multiple Books Progress
+  type: http
+  seq: 3
+
+http:
+  method: POST
+  url: '{{base_url}}/api/sync/kobo/markup'
+  auth: inherit
+  headers:
+    - key: Content-Type
+      value: application/json
+    - key: x-kobo-device
+      value: '{"DeviceId":"{{kobo_device_id}}","Model":"Kobo Aura"}'
+  body:
+    type: json
+    json:
+      ReadingSync:
+        - ContentId: book-1-uuid
+          PercentRead: 25.0
+          EntitlementId: entitlement-1
+          RemainingTimeMinutes: 240
+          FirstReadTime: '2026-01-25T10:00:00Z'
+          LastModified: '2026-01-30T18:00:00Z'
+        - ContentId: book-2-uuid
+          PercentRead: 78.5
+          EntitlementId: entitlement-2
+          RemainingTimeMinutes: 45
+          FirstReadTime: '2026-01-25T14:00:00Z'
+          LastModified: '2026-01-30T20:00:00Z'
+      BookmarkSync: []
+
+docs: |-
+  ## Sync Multiple Books Progress
+
+  Synchronizes reading progress for multiple books in a single request.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/kobo/markup
+
+  **Authentication:** Bearer token
+
+  **Headers:**
+  - `Authorization`: Bearer {{kobo_device_token}}
+  - `x-kobo-device`: Device information (Model: "Kobo Aura")
+
+  **Request Body:**
+  - `ReadingSync` (array): Multiple progress items
+    - Each item contains: ContentId, PercentRead, EntitlementId, etc.
+  - `BookmarkSync` (array): Empty for progress-only batch
+
+  **Response:**
+  - `total` (integer): Total items in request
+  - `synced` (integer): Successfully synced
+  - `failed` (integer): Failed items
+  - `results` (array): Per-item results
+    - `ContentId` (string): Book UUID
+    - `status` (string): `synced`, `failed`, `skipped`
+    - `error` (string, optional): Error message if failed
+
+  **Status Codes:**
+  - 200: Batch sync completed
+  - 207: Multi-status (some succeeded, some failed)
+  - 401: Unauthorized
+  - 413: Payload too large (>1MB)
+
+  **Batch Sync Advantages:**
+  - Efficient sync of entire library
+  - Reduces HTTP overhead
+  - Faster for devices with many books
+  - Atomic operation (all or nothing by default)
+
+  **Kobo Batch Sync Behavior:**
+  - Triggered when device connects after being offline
+  - Occurs during manual "Sync now" operation
+  - Limited to 100 books per request
+  - Progress updates shown on device
+  - Failed items retried individually
+
+  **Performance:**
+  - Typical batch: 10-50 books in 1-3 seconds
+  - Large batch: 50-100 books in 3-8 seconds
+  - Timeout: 30 seconds
+  - Rate limit: 10 batches per minute per device
+
+  **Use Cases:**
+  - Initial device sync after registration
+  - Catch-up sync after extended offline period
+  - Library-wide progress update
+  - Pre-sync before device firmware update
@@ -0,0 +1,84 @@
+info:
+  name: Sync Progress with Bookmarks
+  type: http
+  seq: 2
+
+http:
+  method: POST
+  url: '{{base_url}}/api/sync/kobo/markup'
+  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:
+      ReadingSync:
+        - ContentId: book-uuid
+          PercentRead: 42.3
+          EntitlementId: entitlement-id
+          RemainingTimeMinutes: 138
+          FirstReadTime: '2026-01-25T10:00:00Z'
+          LastModified: '2026-01-30T20:00:00Z'
+      BookmarkSync:
+        - ContentId: book-uuid
+          BookmarkText: highlighted text passage
+          BookmarkType: annotation
+          BookmarkTitle: Chapter 3
+
+docs: |-
+  ## Sync Progress with Bookmarks
+
+  Synchronizes reading progress and highlights/annotations from Kobo device.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/kobo/markup
+
+  **Authentication:** Bearer token
+
+  **Headers:**
+  - `Authorization`: Bearer {{kobo_device_token}}
+  - `x-kobo-device`: Device information JSON
+
+  **Request Body:**
+  - `ReadingSync` (array): Progress items (see Sync Reading Progress)
+  - `BookmarkSync` (array): Highlights and annotations
+    - `ContentId` (string): Book UUID
+    - `BookmarkText` (string): Highlighted text or note content
+    - `BookmarkType` (string): Type of bookmark
+      - `annotation`: Highlighted text
+      - `note`: Personal note
+      - `bookmark`: Location bookmark
+    - `BookmarkTitle` (string): Reference (e.g., chapter name)
+    - `ChapterID` (string, optional): Chapter identifier
+    - `DateCreated` (string, optional): Creation timestamp
+
+  **Response:**
+  - `progress_synced` (integer): Progress items synced
+  - `bookmarks_synced` (integer): Bookmark items synced
+  - `conflicts_resolved` (integer): Number of conflicts auto-resolved
+  - `timestamp` (string): Sync timestamp
+  - `details` (object): Sync breakdown by type
+
+  **Status Codes:**
+  - 200: Successful sync
+  - 401: Unauthorized
+  - 400: Invalid data
+
+  **Kobo Highlight Features:**
+  - 5 highlight colors (yellow, green, blue, pink, orange)
+  - Chapter-based organization
+  - Linked to reading progress
+  - Appears in Kobo "Notebook" view
+  - Can be exported from device
+  - Syncs across all user devices
+
+  **Annotation Sync:**
+  - Highlight text preserved exactly
+  - Color mapped to system colors
+  - Chapter reference maintained
+  - Location data converted to standard format
+  - Notes attached to highlights synced separately
@@ -0,0 +1,84 @@
+info:
+  name: Sync Reading Progress
+  type: http
+  seq: 1
+
+http:
+  method: POST
+  url: '{{base_url}}/api/sync/kobo/markup'
+  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:
+      ReadingSync:
+        - ContentId: book-uuid-here
+          PercentRead: 45.6
+          EntitlementId: entitlement-id-here
+          RemainingTimeMinutes: 120
+          FirstReadTime: '2026-01-25T10:00:00Z'
+          LastModified: '2026-01-30T20:00:00Z'
+      BookmarkSync: []
+
+docs: |-
+  ## Sync Kobo Reading Progress
+
+  Synchronizes reading progress from a Kobo device to the server using Bearer token authentication.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/kobo/markup
+
+  **Authentication:** Bearer token (in Authorization header)
+
+  **Headers:**
+  - `Authorization`: Bearer {{kobo_device_token}}
+  - `x-kobo-device`: JSON-encoded device info
+    - `DeviceId`: Kobo device identifier
+    - `Model`: Device model (e.g., "Kobo Clara", "Kobo Libra", "Kobo Aura")
+
+  **Request Body:**
+  - `ReadingSync` (array): Reading progress items
+    - `ContentId` (string): Book/Content UUID
+    - `PercentRead` (number): Reading progress 0-100
+    - `EntitlementId` (string): Kobo entitlement ID
+    - `RemainingTimeMinutes` (integer): Estimated reading time remaining
+    - `FirstReadTime` (string): ISO 8601 timestamp when first opened
+    - `LastModified` (string): ISO 8601 timestamp of last progress update
+  - `BookmarkSync` (array): Empty array for progress-only sync
+
+  **Response:**
+  - `synced` (integer): Number of items synced
+  - `failed` (integer): Number of items that failed to sync
+  - `timestamp` (string): Server timestamp of sync
+  - `books` (array): Synced book data
+    - `ContentId` (string): Book UUID
+    - `status` (string): `synced`, `failed`, `skipped`
+    - `server_percent` (number): Server-side progress (for conflict detection)
+
+  **Status Codes:**
+  - 200: Sync successful
+  - 401: Invalid device token
+  - 403: Device not approved
+  - 400: Invalid request format
+
+  **Authentication Methods:**
+  This endpoint uses **Bearer token authentication** (token in Authorization header).
+  Alternative: Use `/sync/kobo/{token}/markup` with token in URL path.
+
+  **Kobo Sync Features:**
+  - Native Kobo sync protocol
+  - Supports Kobo Clara, Libra, Aura, Forma, Sage, Elipsa
+  - Progress percentage tracking
+  - Reading time estimation
+  - Cross-device synchronization
+  - Automatic conflict resolution (most recent wins)
+
+  **Sync Frequency:**
+  - Kobo devices auto-sync every 15-30 minutes when connected to WiFi
+  - Manual sync available from device settings
+  - Sync triggers on: device wake, book close, WiFi connection
@@ -0,0 +1,92 @@
+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
@@ -0,0 +1,106 @@
+info:
+  name: Sync with Annotations
+  type: http
+  seq: 4
+
+http:
+  method: POST
+  url: '{{base_url}}/api/sync/kobo/markup'
+  auth: inherit
+  headers:
+    - key: Content-Type
+      value: application/json
+    - key: x-kobo-device
+      value: '{"DeviceId":"{{kobo_device_id}}","Model":"Kobo Libra"}'
+  body:
+    type: json
+    json:
+      ReadingSync:
+        - ContentId: book-uuid
+          PercentRead: 55.0
+          EntitlementId: entitlement-id
+          RemainingTimeMinutes: 120
+          FirstReadTime: '2026-01-25T10:00:00Z'
+          LastModified: '2026-01-30T20:00:00Z'
+      BookmarkSync:
+        - ContentId: book-uuid
+          BookmarkText: Important quote
+          BookmarkType: annotation
+          BookmarkTitle: Chapter 4 - The Truth
+        - ContentId: book-uuid
+          BookmarkText: Another quote
+          BookmarkType: annotation
+          BookmarkTitle: Chapter 5
+        - ContentId: book-uuid
+          BookmarkText: Note to myself
+          BookmarkType: note
+          BookmarkTitle: Personal note
+
+docs: |-
+  ## Sync with Multiple Annotations
+
+  Synchronizes reading progress with multiple highlights and notes.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/kobo/markup
+
+  **Authentication:** Bearer token
+
+  **Headers:**
+  - `Authorization`: Bearer {{kobo_device_token}}
+  - `x-kobo-device`: Device info (Model: "Kobo Libra")
+
+  **Request Body:**
+  - `ReadingSync` (array): Single book progress
+  - `BookmarkSync` (array): Multiple annotations
+    - Can include highlights (annotation type)
+    - Can include notes (note type)
+    - Each has: ContentId, BookmarkText, BookmarkType, BookmarkTitle
+
+  **Response:**
+  - `progress_synced` (boolean): Progress update status
+  - `annotations_synced` (integer): Number of annotations synced
+  - `highlights_count` (integer): Highlights synced
+  - `notes_count` (integer): Notes synced
+  - `conflicts` (array): Any annotation conflicts resolved
+  - `timestamp` (string): Sync completion time
+
+  **Status Codes:**
+  - 200: Successful sync
+  - 401: Unauthorized
+  - 400: Invalid annotation data
+
+  **Kobo Annotation Types:**
+  - **Highlights:** Selected text passages
+    - 5 preset colors available
+    - Can have chapter titles
+    - Exportable to PDF/Mobile
+  - **Notes:** Personal annotations
+    - Free-form text
+    - Can be attached to highlights
+    - Separate from highlights
+  - **Bookmarks:** Location markers
+    - Chapter positions
+    - Quick navigation
+
+  **Sync Behavior:**
+  - Duplicates detected by content matching
+  - Most recent edit wins conflicts
+  - Annotations linked to book content
+  - Chapter references preserved
+  - Order maintained from device
+
+  **Kobo Notebook Export:**
+  - All annotations appear in Kobo "Notebook"
+  - Can be exported to PDF
+  - Can be exported to Mobile (text)
+  - Organized by book
+  - Shows highlight context
+
+  **Use Cases:**
+  - Study and research
+  - Book club discussion prep
+  - Content review
+  - Sharing insights
+  - Personal learning archive
@@ -0,0 +1,45 @@
+info:
+  name: Kobo Bookmark Sync
+  type: http
+  seq: 3
+http:
+  method: POST
+  url: '{{base_url}}/api/v1/kobo/bookmark'
+  auth: inherit
+  body:
+    type: json
+    jsonBody: "{\n    \"BookmarkSync\": [\n      {\n        \"BookmarkId\": \"bookmark_2\"\
+      ,\n        \"ContentId\": \"kobo_xyz789\",\n        \"BookmarkText\": \"Important\
+      \ note\",\n        \"BookmarkType\": \"bookmark\",\n        \"DateCreated\"\
+      : \"2026-01-31T12:00:00Z\""
+  headers:
+  - key: Authorization
+    value: Bearer {{device_token
+
+docs: |-
+  ## Kobo Bookmark Sync
+  
+    Synchronizes bookmarks from a Kobo device to the Bookhoard server.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/v1/kobo/bookmark
+  
+    **Authentication:** Bearer token (device token)
+  
+    **Request Body:**
+    - `BookmarkSync` (array): Array of bookmark objects
+      - `BookmarkId` (string): Unique bookmark ID
+      - `ContentId` (string): Book/content ID
+      - `BookmarkText` (string): Bookmark text or note
+      - `BookmarkType` (string): Type (bookmark, highlight, note)
+      - `DateCreated` (string): ISO 8601 timestamp
+  
+    **Response:**
+    - `Status` (string): Sync status (Success, Partial)
+    - `BookmarksSynced` (number): Number of bookmarks synced
+  
+    **Status Codes:**
+    - 200: Success
+    - 401: Unauthorized
+    - 500: Internal server error
@@ -0,0 +1,19 @@
+info:
+  name: Kobo Initialization - URL Path Token
+  type: http
+  seq: 4
+http:
+  method: GET
+  url: '{{base_url}}/sync/kobo/{{kobo_device_token}}/v1/initialization'
+  auth: none
+  body:
+    type: none
+
+docs: |-
+  ## Kobo Initialization - URL Path Token
+  
+    Returns initialization data for Kobo device using token in URL path.
+  
+    **Method:** GET
+  
+    **Endpoint:** /sync/kobo/{kobo_device_token
@@ -0,0 +1,19 @@
+info:
+  name: Get Library - URL Path Token
+  type: http
+  seq: 3
+http:
+  method: GET
+  url: '{{base_url}}/sync/kobo/{{kobo_device_token}}/library'
+  auth: none
+  body:
+    type: none
+
+docs: |-
+  ## Get Kobo Library - URL Path Token
+  
+    Retrieves library metadata for Kobo device using token in URL path.
+  
+    **Method:** GET
+  
+    **Endpoint:** /sync/kobo/{kobo_device_token
@@ -0,0 +1,39 @@
+info:
+  name: Get Unlinked Books - User View
+  type: http
+  seq: 4
+http:
+  method: GET
+  url: '{{base_url}}/api/sync/unlinked-books'
+  auth: inherit
+  body:
+    type: none
+  headers:
+  - key: Authorization
+    value: Bearer {{user_token
+
+docs: |-
+  ## Get Unlinked Books - User View
+  
+    Retrieves all unlinked books for the authenticated user that need manual linking.
+  
+    **Method:** GET
+  
+    **Endpoint:** /api/sync/unlinked-books
+  
+    **Authentication:** Bearer token
+  
+    **Response:**
+    - `unlinked` (array): Array of unlinked book objects
+      - `id` (string): Unlinked book UUID
+      - `title` (string): Book title
+      - `author` (string): Book author
+      - `device_id` (string): Source device ID
+      - `device_name` (string): Source device name
+      - `detected_at` (string): Detection timestamp
+    - `total` (number): Total count of unlinked books
+  
+    **Status Codes:**
+    - 200: Success
+    - 401: Unauthorized
+    - 500: Internal server error
@@ -0,0 +1,34 @@
+info:
+  name: Kobo Initialization
+  type: http
+  seq: 1
+http:
+  method: GET
+  url: '{{base_url}}/api/v1/kobo/initialization'
+  auth: inherit
+  body:
+    type: none
+  headers:
+  - key: Authorization
+    value: Bearer {{device_token
+
+docs: |-
+  ## Kobo Initialization
+  
+    Initializes Kobo device sync, returning device resources and account information.
+  
+    **Method:** GET
+  
+    **Endpoint:** /api/v1/kobo/initialization
+  
+    **Authentication:** Bearer token (device token)
+  
+    **Response:**
+    - `ContentId` (string): Device content ID
+    - `Categories` (array): Available categories/collections
+    - `BookhoardUUID` (string): Bookhoard instance UUID
+  
+    **Status Codes:**
+    - 200: Success
+    - 401: Unauthorized
+    - 500: Internal server error
@@ -0,0 +1,43 @@
+info:
+  name: Link Unlinked Book - Manual Resolution
+  type: http
+  seq: 5
+http:
+  method: POST
+  url: '{{base_url}}/api/sync/link-book'
+  auth: inherit
+  body:
+    type: json
+    jsonBody: "{\n    \"unlinked_book_id\": \"{{unlinked_book_id"
+  headers:
+  - key: Authorization
+    value: Bearer {{user_token
+
+docs: |-
+  ## Link Unlinked Book - Manual Resolution
+  
+    Manually links an unlinked book to a media item in the library.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/sync/link-book
+  
+    **Authentication:** Bearer token
+  
+    **Request Body:**
+    - `unlinked_book_id` (string): Unlinked book UUID
+    - `media_item_id` (string): Media item UUID to link to
+    - `confidence_score` (number): Match confidence (0-1, 1.0 for manual)
+  
+    **Response:**
+    - `status` (string): Link status (linked)
+    - `unlinked_book_id` (string): Unlinked book UUID
+    - `media_item_id` (string): Media item UUID
+    - `message` (string): Success message
+  
+    **Status Codes:**
+    - 200: Success - book linked
+    - 400: Invalid request
+    - 401: Unauthorized
+    - 404: Book or media item not found
+    - 500: Internal server error
@@ -0,0 +1,52 @@
+info:
+  name: Kobo Markup Sync
+  type: http
+  seq: 2
+http:
+  method: POST
+  url: '{{base_url}}/api/v1/kobo/markup'
+  auth: inherit
+  body:
+    type: json
+    jsonBody: "{\n    \"ReadingSync\": [\n      {\n        \"ContentId\": \"kobo_abc123def456\"\
+      ,\n        \"PercentRead\": 60.0,\n        \"RemainingTimeMin\": 120,\n    \
+      \    \"ReadingEvent\": \"BookRead\",\n        \"LastModified\": \"2026-01-31T12:00:00Z\""
+  headers:
+  - key: Authorization
+    value: Bearer {{device_token
+
+docs: |-
+  ## Kobo Markup Sync
+  
+    Synchronizes reading progress and markup (highlights, bookmarks) from a Kobo device.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/v1/kobo/markup
+  
+    **Authentication:** Bearer token (device token)
+  
+    **Request Body:**
+    - `ReadingSync` (array, optional): Reading progress data
+      - `ContentId` (string): Book/content ID
+      - `PercentRead` (number): Percentage read (0-100)
+      - `RemainingTimeMin` (number): Remaining time in minutes
+      - `ReadingEvent` (string): Event type (BookRead, etc.)
+      - `LastModified` (string): ISO 8601 timestamp
+    - `BookmarkSync` (array, optional): Bookmark/highlight data
+      - `BookmarkId` (string): Unique bookmark ID
+      - `ContentId` (string): Book/content ID
+      - `BookmarkText` (string): Highlighted/bookmarked text
+      - `BookmarkType` (string): Type (annotation, bookmark)
+      - `DateCreated` (string): ISO 8601 timestamp
+    - `Metadata` (boolean): Whether to include metadata
+  
+    **Response:**
+    - `Status` (string): Sync status (Success, Partial)
+    - `MarkupsSynced` (number): Number of markups synced
+    - `BookmarksSynced` (number): Number of bookmarks synced
+  
+    **Status Codes:**
+    - 200: Success
+    - 401: Unauthorized
+    - 500: Internal server error
@@ -0,0 +1,25 @@
+info:
+  name: Sync Bookmark - URL Path Token
+  type: http
+  seq: 2
+http:
+  method: POST
+  url: '{{base_url}}/sync/kobo/{{kobo_device_token}}/bookmark'
+  auth: none
+  body:
+    type: json
+    jsonBody: "{\n    \"ContentId\": \"book-uuid\",\n    \"BookmarkText\": \"Highlighted\
+      \ text\",\n    \"BookmarkType\": \"annotation\",\n    \"BookmarkTitle\": \"\
+      Chapter 3\""
+  headers:
+  - key: Content-Type
+    value: application/json
+
+docs: |-
+  ## Sync Bookmark - URL Path Token
+  
+    Synchronizes bookmarks and annotations from Kobo device using token in URL path.
+  
+    **Method:** POST
+  
+    **Endpoint:** /sync/kobo/{kobo_device_token
@@ -0,0 +1,26 @@
+info:
+  name: Sync Markup - URL Path Token
+  type: http
+  seq: 1
+http:
+  method: POST
+  url: '{{base_url}}/sync/kobo/{{kobo_device_token}}/markup'
+  auth: none
+  body:
+    type: json
+    jsonBody: "{\n    \"ReadingSync\": [\n      {\n        \"ContentId\": \"book-uuid\"\
+      ,\n        \"PercentRead\": 45.6,\n        \"EntitlementId\": \"entitlement-id\"\
+      ,\n        \"RemainingTimeMinutes\": 120,\n        \"FirstReadTime\": \"2026-01-25T10:00:00Z\"\
+      ,\n        \"LastModified\": \"2026-01-30T20:00:00Z\""
+  headers:
+  - key: Content-Type
+    value: application/json
+
+docs: |-
+  ## Sync Reading Progress - URL Path Token
+  
+    Synchronizes reading progress from Kobo device using token in URL path.
+  
+    **Method:** POST
+  
+    **Endpoint:** /sync/kobo/{kobo_device_token