raindrop-complete.yaml

openapi: 3.1.0
info:
  title: Raindrop.io API
  description: Complete API specification for Raindrop.io bookmark management service
  version: 1.2.0
  contact:
    name: Raindrop.io API
    url: https://developer.raindrop.io
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.raindrop.io/rest/v1
    description: Raindrop.io REST API

security:
  - BearerAuth: []

paths:
  # User endpoints
  /user:
    get:
      operationId: getUserProfile
      summary: Get user profile
      description: Retrieves the authenticated user's profile information
      responses:
        '200':
          description: User profile retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfileResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/ServerError'

  /user/stats:
    get:
      operationId: getUserStats
      summary: Get user statistics
      description: Retrieves account-wide statistics for the authenticated user
      responses:
        '200':
          description: User statistics retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserStatsResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  # Collection endpoints
  /collections:
    get:
      operationId: getAllCollections
      summary: Get all collections
      description: Retrieves all collections for the authenticated user
      responses:
        '200':
          description: Collections retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionsResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  /collections/{parentId}/childrens:
    get:
      operationId: getChildCollections
      summary: Get child collections
      description: Retrieves child collections of a specific parent collection
      parameters:
        - name: parentId
          in: path
          required: true
          schema:
            type: integer
          description: Parent collection ID
      responses:
        '200':
          description: Child collections retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionsResponse'

  /collections/sort:
    put:
      operationId: reorderCollections
      summary: Reorder collections
      description: Change the sort order of collections
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sort:
                  type: string
                  description: Sort order specification
              required:
                - sort
      responses:
        '200':
          description: Collections reordered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultResponse'

  /collections/collapsed:
    put:
      operationId: toggleCollectionsExpansion
      summary: Toggle collections expansion
      description: Expand or collapse collections in the UI
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                collapsed:
                  type: boolean
                  description: Whether collections should be collapsed
              required:
                - collapsed
      responses:
        '200':
          description: Collections expansion toggled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultResponse'

  /collections/clean:
    put:
      operationId: removeEmptyCollections
      summary: Remove empty collections
      description: Remove all empty collections from the account
      responses:
        '200':
          description: Empty collections removed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Number of collections removed

  /collection:
    post:
      operationId: createCollection
      summary: Create a new collection
      description: Creates a new collection with the specified properties
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCollectionRequest'
      responses:
        '201':
          description: Collection created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionItemResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  /collection/{id}:
    get:
      operationId: getCollection
      summary: Get collection details
      description: Retrieves detailed information about a specific collection
      parameters:
        - $ref: '#/components/parameters/CollectionId'
      responses:
        '200':
          description: Collection retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionItemResponse'
        '404':
          $ref: '#/components/responses/NotFoundError'

    put:
      operationId: updateCollection
      summary: Update a collection
      description: Updates properties of an existing collection
      parameters:
        - $ref: '#/components/parameters/CollectionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCollectionRequest'
      responses:
        '200':
          description: Collection updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionItemResponse'

    delete:
      operationId: deleteCollection
      summary: Delete a collection
      description: Permanently deletes a collection and all its bookmarks
      parameters:
        - $ref: '#/components/parameters/CollectionId'
      responses:
        '204':
          description: Collection deleted successfully
        '404':
          $ref: '#/components/responses/NotFoundError'

  /collection/{id}/stats:
    get:
      operationId: getCollectionStats
      summary: Get collection statistics
      description: Retrieves statistics for a specific collection
      parameters:
        - $ref: '#/components/parameters/CollectionId'
      responses:
        '200':
          description: Collection statistics retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionStatsResponse'

  /collection/{id}/sharing:
    put:
      operationId: shareCollection
      summary: Share a collection
      description: Share a collection with specific users or generate public sharing link
      parameters:
        - $ref: '#/components/parameters/CollectionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShareCollectionRequest'
      responses:
        '200':
          description: Collection shared successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShareCollectionResponse'

  /collection/{id}/merge:
    put:
      operationId: mergeCollections
      summary: Merge collections
      description: Merge multiple collections into a target collection
      parameters:
        - $ref: '#/components/parameters/CollectionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                with:
                  type: array
                  items:
                    type: integer
                  description: Array of collection IDs to merge into the target
              required:
                - with
      responses:
        '200':
          description: Collections merged successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultResponse'

  /collection/-99/clear:
    put:
      operationId: emptyTrash
      summary: Empty trash
      description: Permanently delete all bookmarks in the trash collection
      responses:
        '200':
          description: Trash emptied successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultResponse'

  # Bookmark endpoints
  /raindrops/0:
    get:
      operationId: getAllBookmarks
      summary: Get all bookmarks
      description: Retrieves all bookmarks from all collections with filtering options
      parameters:
        - $ref: '#/components/parameters/SearchQuery'
        - $ref: '#/components/parameters/SortOrder'
        - $ref: '#/components/parameters/TagFilter'
        - $ref: '#/components/parameters/ImportantFilter'
        - $ref: '#/components/parameters/DuplicatesFilter'
        - $ref: '#/components/parameters/BrokenFilter'
        - $ref: '#/components/parameters/HighlightFilter'
        - $ref: '#/components/parameters/DomainFilter'
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: Bookmarks retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookmarksResponse'

  /raindrops/{collectionId}:
    get:
      operationId: getBookmarksByCollection
      summary: Get bookmarks from a collection
      description: Retrieves bookmarks from a specific collection with filtering options
      parameters:
        - $ref: '#/components/parameters/CollectionId'
        - $ref: '#/components/parameters/SearchQuery'
        - $ref: '#/components/parameters/SortOrder'
        - $ref: '#/components/parameters/TagFilter'
        - $ref: '#/components/parameters/ImportantFilter'
        - $ref: '#/components/parameters/DuplicatesFilter'
        - $ref: '#/components/parameters/BrokenFilter'
        - $ref: '#/components/parameters/HighlightFilter'
        - $ref: '#/components/parameters/DomainFilter'
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: Bookmarks retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookmarksResponse'

  /raindrops:
    get:
      operationId: searchRaindrops
      summary: Advanced bookmark search
      description: Search bookmarks with advanced filtering options
      parameters:
        - $ref: '#/components/parameters/SearchQuery'
        - $ref: '#/components/parameters/CollectionFilter'
        - name: tags
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by tags
        - name: createdStart
          in: query
          schema:
            type: string
            format: date-time
          description: Filter by creation date (start)
        - name: createdEnd
          in: query
          schema:
            type: string
            format: date-time
          description: Filter by creation date (end)
        - $ref: '#/components/parameters/ImportantFilter'
        - name: media
          in: query
          schema:
            type: string
          description: Filter by media type
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/SortOrder'
      responses:
        '200':
          description: Search results retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookmarksResponse'

    put:
      operationId: batchUpdateBookmarks
      summary: Update multiple bookmarks
      description: Update properties of multiple bookmarks at once
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchUpdateBookmarksRequest'
      responses:
        '200':
          description: Bookmarks updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultResponse'

  /raindrops/single:
    get:
      operationId: getSingleBookmark
      summary: Get detailed information about a single bookmark
      description: Retrieves comprehensive details about a specific bookmark by ID
      parameters:
        - name: id
          in: query
          required: true
          schema:
            type: integer
          description: Bookmark ID
      responses:
        '200':
          description: Bookmark retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookmarkItemResponse'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /raindrops/multiple:
    get:
      operationId: getMultipleBookmarks
      summary: Get multiple bookmarks by IDs
      description: Retrieves multiple bookmarks by their IDs
      parameters:
        - name: ids
          in: query
          required: true
          schema:
            type: string
          description: Comma-separated bookmark IDs
      responses:
        '200':
          description: Bookmarks retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookmarksResponse'

  /raindrops/suggest:
    get:
      operationId: suggestTagsCollectionsCovers
      summary: Suggest tags, collections, and covers based on URL
      description: Get AI-powered suggestions for organizing a bookmark based on its URL
      parameters:
        - name: url
          in: query
          required: true
          schema:
            type: string
            format: uri
          description: URL to analyze for suggestions
      responses:
        '200':
          description: Suggestions retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuggestionsResponse'

  /raindrops/move:
    put:
      operationId: bulkMoveBookmarks
      summary: Move multiple bookmarks
      description: Move multiple bookmarks to a different collection
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkMoveBookmarksRequest'
      responses:
        '200':
          description: Bookmarks moved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultResponse'

  /raindrops/tags:
    put:
      operationId: batchTagBookmarks
      summary: Add or remove tags from bookmarks
      description: Batch operation to add or remove tags from multiple bookmarks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchTagBookmarksRequest'
      responses:
        '200':
          description: Tags updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultResponse'

  /raindrops/delete:
    delete:
      operationId: batchDeleteBookmarks
      summary: Delete multiple bookmarks
      description: Delete multiple bookmarks at once
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  type: array
                  items:
                    type: integer
                  description: Array of bookmark IDs to delete
              required:
                - ids
      responses:
        '200':
          description: Bookmarks deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultResponse'

  # Single bookmark operations
  /raindrop:
    post:
      operationId: createBookmark
      summary: Add a new bookmark
      description: Creates a new bookmark with automatic metadata extraction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBookmarkRequest'
      responses:
        '201':
          description: Bookmark created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookmarkItemResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'

  /raindrop/{id}:
    get:
      operationId: getBookmark
      summary: Get bookmark by ID
      description: Retrieves detailed information about a specific bookmark
      parameters:
        - $ref: '#/components/parameters/BookmarkId'
      responses:
        '200':
          description: Bookmark retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookmarkItemResponse'
        '404':
          $ref: '#/components/responses/NotFoundError'

    put:
      operationId: updateBookmark
      summary: Update a bookmark
      description: Updates properties of an existing bookmark
      parameters:
        - $ref: '#/components/parameters/BookmarkId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBookmarkRequest'
      responses:
        '200':
          description: Bookmark updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookmarkItemResponse'

    delete:
      operationId: deleteBookmark
      summary: Delete a bookmark
      description: Moves a bookmark to trash (soft delete)
      parameters:
        - $ref: '#/components/parameters/BookmarkId'
      responses:
        '204':
          description: Bookmark deleted successfully
        '404':
          $ref: '#/components/responses/NotFoundError'

  /raindrop/{id}/permanent:
    delete:
      operationId: permanentDeleteBookmark
      summary: Permanently delete a bookmark
      description: Permanently deletes a bookmark (cannot be recovered)
      parameters:
        - $ref: '#/components/parameters/BookmarkId'
      responses:
        '204':
          description: Bookmark permanently deleted
        '404':
          $ref: '#/components/responses/NotFoundError'

  /raindrop/{id}/reminder:
    put:
      operationId: setReminder
      summary: Set a reminder for a bookmark
      description: Set or update a reminder notification for a bookmark
      parameters:
        - $ref: '#/components/parameters/BookmarkId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetReminderRequest'
      responses:
        '200':
          description: Reminder set successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookmarkItemResponse'

    delete:
      operationId: deleteReminder
      summary: Delete a bookmark reminder
      description: Remove the reminder notification from a bookmark
      parameters:
        - $ref: '#/components/parameters/BookmarkId'
      responses:
        '200':
          description: Reminder deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookmarkItemResponse'

  /raindrop/{id}/highlights:
    get:
      operationId: getHighlightsForBookmark
      summary: Get highlights for a specific bookmark
      description: Retrieves all text highlights for a given bookmark
      parameters:
        - $ref: '#/components/parameters/BookmarkId'
      responses:
        '200':
          description: Highlights retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HighlightsResponse'

  # File operations
  /raindrop/file:
    put:
      operationId: uploadFile
      summary: Upload a file as a bookmark
      description: Upload a file and create a bookmark from it
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: File to upload
                collectionId:
                  type: string
                  description: Collection ID to add the file to
              required:
                - file
                - collectionId
      responses:
        '201':
          description: File uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookmarkItemResponse'

  /file/{id}:
    get:
      operationId: getFile
      summary: Retrieve a file
      description: Download or retrieve information about an uploaded file
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: File ID
      responses:
        '200':
          description: File retrieved successfully
        '404':
          $ref: '#/components/responses/NotFoundError'

    delete:
      operationId: deleteFile
      summary: Delete a file
      description: Delete an uploaded file
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: File ID
      responses:
        '204':
          description: File deleted successfully
        '404':
          $ref: '#/components/responses/NotFoundError'

  # Highlights
  /highlights:
    get:
      operationId: getAllHighlights
      summary: Get all highlights
      description: Retrieves all highlights from a user's bookmarks with pagination
      parameters:
        - $ref: '#/components/parameters/Page'
        - name: perpage
          in: query
          schema:
            type: integer
            default: 25
            maximum: 50
          description: Number of highlights per page (max 50)
      responses:
        '200':
          description: Highlights retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HighlightsResponse'

    post:
      operationId: addHighlightToBookmark
      summary: Add a new highlight to a bookmark
      description: Creates a new text highlight for a specific bookmark
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateHighlightRequest'
      responses:
        '201':
          description: Highlight created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HighlightItemResponse'

  /highlights/{id}:
    put:
      operationId: updateHighlight
      summary: Update a highlight
      description: Modifies an existing highlight's text, note, or color
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: Highlight ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateHighlightRequest'
      responses:
        '200':
          description: Highlight updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HighlightItemResponse'

    delete:
      operationId: deleteHighlight
      summary: Delete a highlight
      description: Permanently removes a highlight from a bookmark
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: Highlight ID
      responses:
        '204':
          description: Highlight deleted successfully
        '404':
          $ref: '#/components/responses/NotFoundError'

  /highlights/{collectionId}:
    get:
      operationId: getHighlightsByCollection
      summary: Get all highlights in a collection
      description: Retrieves all highlights from bookmarks in a specific collection
      parameters:
        - name: collectionId
          in: path
          required: true
          schema:
            type: integer
          description: Collection ID
        - $ref: '#/components/parameters/Page'
        - name: perpage
          in: query
          schema:
            type: integer
            default: 25
            maximum: 50
          description: Number of highlights per page (max 50)
      responses:
        '200':
          description: Collection highlights retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HighlightsResponse'

  # Tags
  /tags:
    get:
      operationId: getAllTags
      summary: Get all tags used in bookmarks
      description: Retrieves all unique tags used in the user's bookmarks
      responses:
        '200':
          description: Tags retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagsResponse'

  /tags/0:
    get:
      operationId: getAllTagsAlt
      summary: Get all tags (alternative endpoint)
      description: Alternative endpoint to retrieve all tags
      responses:
        '200':
          description: Tags retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagsResponse'

    put:
      operationId: renameOrMergeAllTags
      summary: Rename or merge tags globally
      description: Rename or merge tags across all collections
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagOperationRequest'
      responses:
        '200':
          description: Tag operation completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultResponse'

    delete:
      operationId: deleteAllTags
      summary: Delete multiple tags globally
      description: Delete multiple tags from all bookmarks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tags:
                  type: array
                  items:
                    type: string
                  description: Array of tag names to delete
              required:
                - tags
      responses:
        '200':
          description: Tags deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultResponse'

  /tags/{collectionId}:
    get:
      operationId: getTagsByCollection
      summary: Get tags from a specific collection
      description: Retrieves all tags used in bookmarks within a specific collection
      parameters:
        - $ref: '#/components/parameters/CollectionId'
      responses:
        '200':
          description: Collection tags retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagsResponse'

    put:
      operationId: renameOrMergeCollectionTags
      summary: Rename or merge tags in a collection
      description: Rename or merge tags within a specific collection
      parameters:
        - $ref: '#/components/parameters/CollectionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagOperationRequest'
      responses:
        '200':
          description: Tag operation completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultResponse'

    delete:
      operationId: deleteCollectionTags
      summary: Delete tags from a collection
      description: Delete multiple tags from bookmarks in a specific collection
      parameters:
        - $ref: '#/components/parameters/CollectionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tags:
                  type: array
                  items:
                    type: string
                  description: Array of tag names to delete
              required:
                - tags
      responses:
        '200':
          description: Tags deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultResponse'

  # Import/Export
  /import:
    post:
      operationId: importBookmarks
      summary: Import bookmarks from external services
      description: Import bookmarks from files or external services
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ImportBookmarksRequest'
      responses:
        '200':
          description: Import completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportResponse'

  /import/url:
    post:
      operationId: importFromUrl
      summary: Import bookmarks from URL
      description: Import bookmarks from a remote URL hosting a bookmarks file
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportFromUrlRequest'
      responses:
        '200':
          description: Import initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportJobResponse'

  /import/status:
    get:
      operationId: getImportStatus
      summary: Get import status
      description: Check the status of an ongoing import operation
      responses:
        '200':
          description: Import status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportStatusResponse'

  /export:
    post:
      operationId: exportBookmarks
      summary: Export bookmarks
      description: Export bookmarks in various formats
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportBookmarksRequest'
      responses:
        '200':
          description: Export initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportResponse'

  /export/status:
    get:
      operationId: getExportStatus
      summary: Get export status
      description: Check the status of an ongoing export operation
      responses:
        '200':
          description: Export status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportStatusResponse'

  # Filters
  /filters:
    get:
      operationId: getAvailableFilters
      summary: Get available filters for bookmarks
      description: Returns available filters such as tags, domains, and highlights to refine searches
      responses:
        '200':
          description: Filters retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FiltersResponse'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Raindrop.io API access token

  parameters:
    CollectionId:
      name: id
      in: path
      required: true
      schema:
        type: integer
      description: Collection ID

    BookmarkId:
      name: id
      in: path
      required: true
      schema:
        type: integer
      description: Bookmark ID

    SearchQuery:
      name: search
      in: query
      schema:
        type: string
      description: Search query for filtering results

    SortOrder:
      name: sort
      in: query
      schema:
        type: string
        enum:
          - +created
          - -created
          - +title
          - -title
          - +domain
          - -domain
          - +score
          - -score
        default: -created
      description: Sort order for results

    TagFilter:
      name: tag
      in: query
      schema:
        type: string
      description: Filter by specific tag

    ImportantFilter:
      name: important
      in: query
      schema:
        type: boolean
      description: Filter by important flag

    DuplicatesFilter:
      name: duplicates
      in: query
      schema:
        type: boolean
      description: Filter by duplicates

    BrokenFilter:
      name: broken
      in: query
      schema:
        type: boolean
      description: Filter by broken links

    HighlightFilter:
      name: highlight
      in: query
      schema:
        type: boolean
      description: Filter by presence of highlights

    DomainFilter:
      name: domain
      in: query
      schema:
        type: string
      description: Filter by domain

    CollectionFilter:
      name: collection
      in: query
      schema:
        type: integer
      description: Filter by collection ID

    PerPage:
      name: perpage
      in: query
      schema:
        type: integer
        default: 50
        minimum: 1
        maximum: 100
      description: Number of items per page

    Page:
      name: page
      in: query
      schema:
        type: integer
        default: 0
        minimum: 0
      description: Page number for pagination

  responses:
    BadRequestError:
      description: Bad request - invalid parameters or request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

    UnauthorizedError:
      description: Unauthorized - invalid or missing access token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

    NotFoundError:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

    RateLimitError:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

  schemas:
    # Core entity schemas
    Collection:
      type: object
      properties:
        _id:
          type: integer
          description: Collection ID
        title:
          type: string
          description: Collection title
        description:
          type: string
          description: Collection description
        color:
          type: string
          description: Collection color theme
        count:
          type: integer
          description: Number of bookmarks in collection
        public:
          type: boolean
          description: Whether collection is public
        parent:
          type: object
          properties:
            $id:
              type: integer
          description: Parent collection reference
        expanded:
          type: boolean
          description: Whether collection is expanded in UI
        sort:
          type: string
          description: Sort order within parent
        access:
          type: object
          description: Access control settings
        created:
          type: string
          format: date-time
          description: Creation timestamp
        lastUpdate:
          type: string
          format: date-time
          description: Last update timestamp
      required:
        - _id
        - title

    Bookmark:
      type: object
      properties:
        _id:
          type: integer
          description: Bookmark ID
        link:
          type: string
          format: uri
          description: Bookmark URL
        title:
          type: string
          description: Bookmark title
        excerpt:
          type: string
          description: Bookmark description/excerpt
        note:
          type: string
          description: User notes for the bookmark
        type:
          type: string
          enum: [link, article, image, video, document, audio]
          description: Type of bookmark content
        cover:
          type: string
          format: uri
          description: Cover image URL
        tags:
          type: array
          items:
            type: string
          description: Array of tags
        important:
          type: boolean
          description: Whether bookmark is marked as important
        reminder:
          type: object
          properties:
            date:
              type: string
              format: date-time
            note:
              type: string
          description: Reminder settings
        removed:
          type: boolean
          description: Whether bookmark is in trash
        created:
          type: string
          format: date-time
          description: Creation timestamp
        lastUpdate:
          type: string
          format: date-time
          description: Last update timestamp
        domain:
          type: string
          description: Domain of the bookmark URL
        creatorRef:
          type: integer
          description: User ID of creator
        collection:
          type: object
          properties:
            $id:
              type: integer
            title:
              type: string
          description: Collection reference
        highlights:
          type: array
          items:
            $ref: '#/components/schemas/Highlight'
          description: Text highlights for this bookmark
      required:
        - _id
        - link
        - title

    Highlight:
      type: object
      properties:
        _id:
          type: string
          description: Unique highlight ID
        text:
          type: string
          description: Highlighted text content
        note:
          type: string
          description: Optional note for the highlight
        color:
          type: string
          enum: [blue, brown, cyan, gray, green, indigo, orange, pink, purple, red, teal, yellow]
          default: yellow
          description: Highlight color
        created:
          type: string
          format: date-time
          description: Creation timestamp
        lastUpdate:
          type: string
          format: date-time
          description: Last update timestamp
        title:
          type: string
          description: Title of the parent bookmark
        link:
          type: string
          format: uri
          description: URL of the parent bookmark
        domain:
          type: string
          description: Domain of the parent bookmark
        excerpt:
          type: string
          description: Context around the highlight
        tags:
          type: array
          items:
            type: string
          description: Tags from the parent bookmark
        raindrop:
          type: object
          properties:
            _id:
              type: integer
            title:
              type: string
            link:
              type: string
            collection:
              type: object
              properties:
                $id:
                  type: integer
          description: Reference to parent bookmark
      required:
        - _id
        - text

    Tag:
      type: object
      properties:
        _id:
          type: string
          description: Tag name
        count:
          type: integer
          description: Number of bookmarks with this tag
      required:
        - _id
        - count

    User:
      type: object
      properties:
        _id:
          type: integer
          description: User ID
        email:
          type: string
          format: email
          description: User email address
        fullName:
          type: string
          description: User's full name
        avatar:
          type: string
          format: uri
          description: Avatar image URL
        pro:
          type: boolean
          description: Whether user has Pro subscription
        proExpire:
          type: string
          format: date-time
          description: Pro subscription expiration date
        registered:
          type: string
          format: date-time
          description: Registration date
        lastUpdate:
          type: string
          format: date-time
          description: Last profile update
      required:
        - _id
        - email

    # Request schemas
    CreateCollectionRequest:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          description: Collection title
        public:
          type: boolean
          default: false
          description: Whether collection should be public
        parent:
          type: object
          properties:
            $id:
              type: integer
          description: Parent collection reference
        color:
          type: string
          description: Collection color theme
        description:
          type: string
          description: Collection description
      required:
        - title

    UpdateCollectionRequest:
      type: object
      properties:
        title:
          type: string
          description: Collection title
        public:
          type: boolean
          description: Whether collection should be public
        parent:
          type: object
          properties:
            $id:
              type: integer
          description: Parent collection reference
        color:
          type: string
          description: Collection color theme
        description:
          type: string
          description: Collection description

    ShareCollectionRequest:
      type: object
      properties:
        level:
          type: string
          enum: [view, edit, remove]
          description: Sharing permission level
        emails:
          type: array
          items:
            type: string
            format: email
          description: Email addresses to share with
      required:
        - level

    CreateBookmarkRequest:
      type: object
      properties:
        link:
          type: string
          format: uri
          description: Bookmark URL
        title:
          type: string
          description: Bookmark title (auto-extracted if not provided)
        excerpt:
          type: string
          description: Bookmark description
        tags:
          type: array
          items:
            type: string
          description: Array of tags
        important:
          type: boolean
          default: false
          description: Whether bookmark is important
        collection:
          type: object
          properties:
            $id:
              type: integer
          description: Target collection reference
        pleaseParse:
          type: object
          description: Settings for content parsing
      required:
        - link

    UpdateBookmarkRequest:
      type: object
      properties:
        link:
          type: string
          format: uri
          description: Bookmark URL
        title:
          type: string
          description: Bookmark title
        excerpt:
          type: string
          description: Bookmark description
        note:
          type: string
          description: User notes
        tags:
          type: array
          items:
            type: string
          description: Array of tags
        important:
          type: boolean
          description: Whether bookmark is important
        collection:
          type: object
          properties:
            $id:
              type: integer
          description: Target collection reference
        cover:
          type: string
          format: uri
          description: Cover image URL

    BatchUpdateBookmarksRequest:
      type: object
      properties:
        ids:
          type: array
          items:
            type: integer
          description: Array of bookmark IDs to update
        tags:
          type: array
          items:
            type: string
          description: Tags to set on bookmarks
        collection:
          type: object
          properties:
            $id:
              type: integer
          description: Collection to move bookmarks to
        important:
          type: boolean
          description: Whether bookmarks should be marked important
        broken:
          type: boolean
          description: Whether bookmarks should be marked as broken
      required:
        - ids

    BulkMoveBookmarksRequest:
      type: object
      properties:
        ids:
          type: array
          items:
            type: integer
          description: Array of bookmark IDs to move
        collection:
          type: object
          properties:
            $id:
              type: integer
          description: Target collection
      required:
        - ids
        - collection

    BatchTagBookmarksRequest:
      type: object
      properties:
        ids:
          type: array
          items:
            type: integer
          description: Array of bookmark IDs
        tags:
          type: array
          items:
            type: string
          description: Tags to add or remove
        replace:
          type: boolean
          default: false
          description: Whether to replace existing tags or add to them
      required:
        - ids
        - tags

    SetReminderRequest:
      type: object
      properties:
        date:
          type: string
          format: date-time
          description: Reminder date and time
        note:
          type: string
          description: Optional reminder note
      required:
        - date

    CreateHighlightRequest:
      type: object
      properties:
        raindrop:
          type: object
          properties:
            $id:
              type: integer
          description: Bookmark reference
        text:
          type: string
          description: Highlighted text
        note:
          type: string
          description: Optional note for the highlight
        color:
          type: string
          enum: [blue, brown, cyan, gray, green, indigo, orange, pink, purple, red, teal, yellow]
          default: yellow
          description: Highlight color
      required:
        - raindrop
        - text

    UpdateHighlightRequest:
      type: object
      properties:
        text:
          type: string
          description: Updated highlight text
        note:
          type: string
          description: Updated note
        color:
          type: string
          enum: [blue, brown, cyan, gray, green, indigo, orange, pink, purple, red, teal, yellow]
          description: Updated highlight color

    TagOperationRequest:
      type: object
      properties:
        from:
          type: string
          description: Original tag name (for rename operation)
        to:
          type: string
          description: New tag name
        tags:
          type: array
          items:
            type: string
          description: Array of tag names (for merge operation)

    ImportBookmarksRequest:
      type: object
      properties:
        file:
          type: string
          format: binary
          description: Bookmarks file to import
        collection:
          type: string
          description: Collection ID to import into
        format:
          type: string
          enum: [html, csv, pocket, instapaper, netscape, readwise]
          description: Format of the import file
        mode:
          type: string
          enum: [add, replace]
          default: add
          description: Import mode
        parse:
          type: boolean
          default: true
          description: Whether to parse content during import
      required:
        - file

    ImportFromUrlRequest:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: URL of bookmarks file to import
        parse:
          type: boolean
          default: true
          description: Whether to parse imported bookmarks
        collection:
          type: object
          properties:
            $id:
              type: integer
            title:
              type: string
          description: Collection details to import into
      required:
        - url

    ExportBookmarksRequest:
      type: object
      properties:
        collection:
          type: integer
          description: Collection ID to export (omit for all bookmarks)
        format:
          type: string
          enum: [csv, html, pdf]
          description: Export format
        broken:
          type: boolean
          default: false
          description: Include broken bookmarks
        duplicates:
          type: boolean
          default: false
          description: Include duplicate bookmarks
      required:
        - format

    # Response schemas
    UserProfileResponse:
      type: object
      properties:
        result:
          type: boolean
        user:
          $ref: '#/components/schemas/User'
      required:
        - result
        - user

    UserStatsResponse:
      type: object
      properties:
        result:
          type: boolean
        stats:
          type: object
          properties:
            bookmarks:
              type: integer
            collections:
              type: integer
            highlights:
              type: integer
            tags:
              type: integer
      required:
        - result
        - stats

    CollectionStatsResponse:
      type: object
      properties:
        result:
          type: boolean
        stats:
          type: object
          properties:
            bookmarks:
              type: integer
            highlights:
              type: integer
            tags:
              type: integer
      required:
        - result
        - stats

    CollectionsResponse:
      type: object
      properties:
        result:
          type: boolean
        items:
          type: array
          items:
            $ref: '#/components/schemas/Collection'
      required:
        - result
        - items

    CollectionItemResponse:
      type: object
      properties:
        result:
          type: boolean
        item:
          $ref: '#/components/schemas/Collection'
      required:
        - result
        - item

    ShareCollectionResponse:
      type: object
      properties:
        result:
          type: boolean
        link:
          type: string
          format: uri
          description: Public sharing link
        access:
          type: array
          items:
            type: object
            properties:
              email:
                type: string
                format: email
              level:
                type: string
                enum: [view, edit]
          description: List of users with access
      required:
        - result
        - link
        - access

    BookmarksResponse:
      type: object
      properties:
        result:
          type: boolean
        items:
          type: array
          items:
            $ref: '#/components/schemas/Bookmark'
        count:
          type: integer
          description: Total number of matching bookmarks
        collectionId:
          type: integer
          description: Collection ID that was searched
      required:
        - result
        - items

    BookmarkItemResponse:
      type: object
      properties:
        result:
          type: boolean
        item:
          $ref: '#/components/schemas/Bookmark'
      required:
        - result
        - item

    HighlightsResponse:
      type: object
      properties:
        result:
          type: boolean
        items:
          type: array
          items:
            $ref: '#/components/schemas/Highlight'
      required:
        - result
        - items

    HighlightItemResponse:
      type: object
      properties:
        result:
          type: boolean
        item:
          $ref: '#/components/schemas/Highlight'
      required:
        - result
        - item

    TagsResponse:
      type: object
      properties:
        result:
          type: boolean
        items:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
      required:
        - result
        - items

    SuggestionsResponse:
      type: object
      properties:
        result:
          type: boolean
        item:
          type: object
          properties:
            tags:
              type: array
              items:
                type: string
            collections:
              type: array
              items:
                type: object
                properties:
                  _id:
                    type: integer
                  title:
                    type: string
            covers:
              type: array
              items:
                type: string
                format: uri
      required:
        - result
        - item

    ImportResponse:
      type: object
      properties:
        result:
          type: boolean
        items:
          type: array
          items:
            type: object
            properties:
              _id:
                type: integer
              link:
                type: string
        imported:
          type: integer
          description: Number of bookmarks imported
        duplicates:
          type: integer
          description: Number of duplicates found
      required:
        - result
        - items

    ImportJobResponse:
      type: object
      properties:
        result:
          type: boolean
        item:
          type: object
          properties:
            _id:
              type: string
              description: Import job ID
      required:
        - result
        - item

    ImportStatusResponse:
      type: object
      properties:
        result:
          type: boolean
        status:
          type: string
          enum: [in-progress, ready, error]
          description: Current import status
        progress:
          type: integer
          minimum: 0
          maximum: 100
          description: Import progress percentage
        imported:
          type: integer
          description: Number of bookmarks imported so far
        duplicates:
          type: integer
          description: Number of duplicates found
        error:
          type: string
          description: Error message if status is 'error'
      required:
        - result
        - status

    ExportResponse:
      type: object
      properties:
        result:
          type: boolean
        url:
          type: string
          format: uri
          description: Download URL for the exported file
      required:
        - result
        - url

    ExportStatusResponse:
      type: object
      properties:
        result:
          type: boolean
        status:
          type: string
          enum: [in-progress, ready, error]
          description: Current export status
        progress:
          type: integer
          minimum: 0
          maximum: 100
          description: Export progress percentage
        url:
          type: string
          format: uri
          description: Download URL when ready
        error:
          type: string
          description: Error message if status is 'error'
      required:
        - result
        - status

    FiltersResponse:
      type: object
      properties:
        result:
          type: boolean
        tags:
          type: array
          items:
            type: string
          description: Available tag filters
        domains:
          type: array
          items:
            type: string
          description: Available domain filters
        highlights:
          type: array
          items:
            type: string
          description: Available highlight filters
      required:
        - result
        - tags
        - domains
        - highlights

    ResultResponse:
      type: object
      properties:
        result:
          type: boolean
          description: Whether the operation was successful
      required:
        - result

    ErrorResponse:
      type: object
      properties:
        result:
          type: boolean
          default: false
        error:
          type: string
          description: Error message
        errorMessage:
          type: string
          description: Detailed error description
        errorCode:
          type: integer
          description: Error code
      required:
        - result
        - error