autobrr RSS API

openapi: 3.2.0
info:
  title: qui RSS API
  description: 'qui API for managing multiple qBittorrent instances.

    If allowedHosts is configured, a missing, invalid, or unlisted received Host

    returns HTTP 400 before authentication or routing. X-Forwarded-Host is ignored.

    Request ports do not affect matching. Only direct loopback GET and HEAD

    requests to /health, /healthz/readiness, and /healthz/liveness bypass the list.


    For automation create and update requests, set `conditions.category.enabled` to `true`

    and `conditions.category.category` to an empty string to remove the torrent category.

    Set `conditions.category.enabled` to `false` to disable the category action.'
  version: 1.0.0
  license:
    name: GPL-2.0-or-later
    url: https://opensource.org/licenses/GPL-2.0
servers:
- url: http://localhost:7476
  description: Local development server
- url: /
  description: Current server
security:
- ApiKeyAuth: []
- SessionAuth: []
tags:
- name: RSS
  description: RSS feed and auto-download rule management
paths:
  /api/instances/{instanceID}/rss/events:
    get:
      tags:
      - RSS
      summary: RSS events stream (SSE)
      description: Server-Sent Events stream for real-time RSS feed updates
      parameters:
      - $ref: '#/components/parameters/instanceID'
      responses:
        '200':
          description: SSE stream established
          content:
            text/event-stream:
              schema:
                type: string
                description: Server-Sent Events stream with feed updates
        '400':
          description: Invalid instance ID
        '409':
          description: Instance is disabled
        '500':
          description: Failed to establish SSE stream
      operationId: getApiInstancesByInstanceIDRssEvents
      x-operation-id-source: derived
  /api/instances/{instanceID}/rss/items:
    get:
      tags:
      - RSS
      summary: Get RSS items
      description: Retrieve all RSS feeds and folders for an instance
      parameters:
      - $ref: '#/components/parameters/instanceID'
      - name: withData
        in: query
        required: false
        schema:
          type: boolean
          default: true
        description: Include article data with feeds
      responses:
        '200':
          description: RSS items retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RSSItems'
        '400':
          description: Invalid instance ID
        '409':
          description: Instance is disabled
        '500':
          description: Failed to get RSS items
      operationId: getApiInstancesByInstanceIDRssItems
      x-operation-id-source: derived
    delete:
      tags:
      - RSS
      summary: Remove RSS item
      description: Remove an RSS feed or folder
      parameters:
      - $ref: '#/components/parameters/instanceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - path
              properties:
                path:
                  type: string
                  description: Path of the item to remove
      responses:
        '200':
          description: Item removed successfully
        '400':
          description: Invalid request
        '409':
          description: Instance is disabled
        '500':
          description: Failed to remove RSS item
      operationId: deleteApiInstancesByInstanceIDRssItems
      x-operation-id-source: derived
  /api/instances/{instanceID}/rss/items/move:
    post:
      tags:
      - RSS
      summary: Move RSS item
      description: Move an RSS feed or folder to a new location
      parameters:
      - $ref: '#/components/parameters/instanceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - itemPath
              properties:
                itemPath:
                  type: string
                  description: Current path of the item
                destPath:
                  type: string
                  description: Destination path (empty for root)
      responses:
        '200':
          description: Item moved successfully
        '400':
          description: Invalid request
        '409':
          description: Instance is disabled
        '500':
          description: Failed to move RSS item
      operationId: postApiInstancesByInstanceIDRssItemsMove
      x-operation-id-source: derived
  /api/instances/{instanceID}/rss/items/refresh:
    post:
      tags:
      - RSS
      summary: Refresh RSS item
      description: Trigger a manual refresh of an RSS feed or folder
      parameters:
      - $ref: '#/components/parameters/instanceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - itemPath
              properties:
                itemPath:
                  type: string
                  description: Path of the item to refresh
      responses:
        '200':
          description: Refresh triggered successfully
        '400':
          description: Invalid request
        '409':
          description: Instance is disabled
        '500':
          description: Failed to refresh RSS item
      operationId: postApiInstancesByInstanceIDRssItemsRefresh
      x-operation-id-source: derived
  /api/instances/{instanceID}/rss/folders:
    post:
      tags:
      - RSS
      summary: Create RSS folder
      description: Create a new RSS folder
      parameters:
      - $ref: '#/components/parameters/instanceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - path
              properties:
                path:
                  type: string
                  description: Path for the new folder
      responses:
        '201':
          description: Folder created successfully
        '400':
          description: Invalid request
        '409':
          description: Instance is disabled
        '500':
          description: Failed to create RSS folder
      operationId: postApiInstancesByInstanceIDRssFolders
      x-operation-id-source: derived
  /api/instances/{instanceID}/rss/feeds:
    post:
      tags:
      - RSS
      summary: Add RSS feed
      description: Add a new RSS feed
      parameters:
      - $ref: '#/components/parameters/instanceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - url
              properties:
                url:
                  type: string
                  format: uri
                  description: URL of the RSS feed
                path:
                  type: string
                  description: Optional folder path to add the feed to
      responses:
        '201':
          description: Feed added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WarningResponse'
        '400':
          description: Invalid request
        '409':
          description: Instance is disabled
        '500':
          description: Failed to add RSS feed
      operationId: postApiInstancesByInstanceIDRssFeeds
      x-operation-id-source: derived
  /api/instances/{instanceID}/rss/feeds/url:
    put:
      tags:
      - RSS
      summary: Set feed URL
      description: Change the URL of an existing RSS feed
      parameters:
      - $ref: '#/components/parameters/instanceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - path
              - url
              properties:
                path:
                  type: string
                  description: Path of the feed
                url:
                  type: string
                  format: uri
                  description: New URL for the feed
      responses:
        '200':
          description: Feed URL updated successfully
        '400':
          description: Invalid request
        '409':
          description: Instance is disabled
        '500':
          description: Failed to set RSS feed URL
      operationId: putApiInstancesByInstanceIDRssFeedsUrl
      x-operation-id-source: derived
  /api/instances/{instanceID}/rss/articles/read:
    post:
      tags:
      - RSS
      summary: Mark articles as read
      description: Mark RSS articles as read
      parameters:
      - $ref: '#/components/parameters/instanceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - itemPath
              properties:
                itemPath:
                  type: string
                  description: Path of the feed
                articleId:
                  type: string
                  description: Optional specific article ID (omit to mark all as read)
      responses:
        '200':
          description: Articles marked as read successfully
        '400':
          description: Invalid request
        '409':
          description: Instance is disabled
        '500':
          description: Failed to mark RSS item as read
      operationId: postApiInstancesByInstanceIDRssArticlesRead
      x-operation-id-source: derived
  /api/instances/{instanceID}/rss/rules:
    get:
      tags:
      - RSS
      summary: Get RSS rules
      description: Retrieve all RSS auto-download rules
      parameters:
      - $ref: '#/components/parameters/instanceID'
      responses:
        '200':
          description: Rules retrieved successfully
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/RSSAutoDownloadRule'
        '400':
          description: Invalid instance ID
        '409':
          description: Instance is disabled
        '500':
          description: Failed to get RSS rules
      operationId: getApiInstancesByInstanceIDRssRules
      x-operation-id-source: derived
    post:
      tags:
      - RSS
      summary: Create or update RSS rule
      description: Create a new rule or update an existing one
      parameters:
      - $ref: '#/components/parameters/instanceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - rule
              properties:
                name:
                  type: string
                  description: Name of the rule
                rule:
                  $ref: '#/components/schemas/RSSAutoDownloadRule'
      responses:
        '201':
          description: Rule created/updated successfully
        '400':
          description: Invalid request
        '409':
          description: Instance is disabled
        '500':
          description: Failed to set RSS rule
      operationId: postApiInstancesByInstanceIDRssRules
      x-operation-id-source: derived
  /api/instances/{instanceID}/rss/rules/reprocess:
    post:
      tags:
      - RSS
      summary: Reprocess RSS rules
      description: Trigger qBittorrent to reprocess all unread articles against rules
      parameters:
      - $ref: '#/components/parameters/instanceID'
      responses:
        '200':
          description: Reprocessing triggered successfully
        '400':
          description: Invalid instance ID
        '409':
          description: Instance is disabled
        '500':
          description: Failed to reprocess RSS rules
      operationId: postApiInstancesByInstanceIDRssRulesReprocess
      x-operation-id-source: derived
  /api/instances/{instanceID}/rss/rules/{ruleName}:
    delete:
      tags:
      - RSS
      summary: Delete RSS rule
      description: Delete an RSS auto-download rule
      parameters:
      - $ref: '#/components/parameters/instanceID'
      - name: ruleName
        in: path
        required: true
        schema:
          type: string
        description: Name of the rule to delete
      responses:
        '200':
          description: Rule deleted successfully
        '400':
          description: Invalid request
        '409':
          description: Instance is disabled
        '500':
          description: Failed to remove RSS rule
      operationId: deleteApiInstancesByInstanceIDRssRulesByRuleName
      x-operation-id-source: derived
  /api/instances/{instanceID}/rss/rules/{ruleName}/rename:
    put:
      tags:
      - RSS
      summary: Rename RSS rule
      description: Rename an existing RSS auto-download rule
      parameters:
      - $ref: '#/components/parameters/instanceID'
      - name: ruleName
        in: path
        required: true
        schema:
          type: string
        description: Current name of the rule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - newName
              properties:
                newName:
                  type: string
                  description: New name for the rule
      responses:
        '200':
          description: Rule renamed successfully
        '400':
          description: Invalid request
        '409':
          description: Instance is disabled
        '500':
          description: Failed to rename RSS rule
      operationId: putApiInstancesByInstanceIDRssRulesByRuleNameRename
      x-operation-id-source: derived
  /api/instances/{instanceID}/rss/rules/{ruleName}/preview:
    get:
      tags:
      - RSS
      summary: Preview RSS rule matches
      description: Get articles that would match an RSS rule
      parameters:
      - $ref: '#/components/parameters/instanceID'
      - name: ruleName
        in: path
        required: true
        schema:
          type: string
        description: Name of the rule to preview
      responses:
        '200':
          description: Matching articles retrieved successfully
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: string
        '400':
          description: Invalid request
        '409':
          description: Instance is disabled
        '500':
          description: Failed to get RSS matching articles
      operationId: getApiInstancesByInstanceIDRssRulesByRuleNamePreview
      x-operation-id-source: derived
components:
  schemas:
    RSSRuleTorrentParams:
      type: object
      properties:
        category:
          type: string
        tags:
          type: array
          items:
            type: string
        save_path:
          type: string
        download_path:
          type: string
        content_layout:
          type: string
        operating_mode:
          type: string
        skip_checking:
          type: boolean
          description: Legacy name of seed_mode. qui returns the same value in both fields.
        seed_mode:
          type: boolean
          description: Skip the hash check. If a request has both fields, seed_mode is used.
        upload_limit:
          type: integer
        download_limit:
          type: integer
        seeding_time_limit:
          type: integer
        inactive_seeding_time_limit:
          type: integer
        share_limit_action:
          type: string
        share_limits_mode:
          type: string
          enum:
          - Default
          - MatchAny
          - MatchAll
          description: Default uses the global share limits mode. qBittorrent 5.3 and later.
        ratio_limit:
          type: number
          format: double
        stopped:
          type: boolean
        stop_condition:
          type: string
        use_auto_tmm:
          type: boolean
        use_download_path:
          type: boolean
        add_to_top_of_queue:
          type: boolean
    WarningResponse:
      type: object
      properties:
        warning:
          type: string
          description: Warning message about partial success
    RSSAutoDownloadRule:
      type: object
      properties:
        enabled:
          type: boolean
        priority:
          type: integer
        mustContain:
          type: string
        mustNotContain:
          type: string
        episodeFilter:
          type: string
        useRegex:
          type: boolean
        affectedFeeds:
          type: array
          items:
            type: string
        ignoreDays:
          type: integer
        lastMatch:
          type: string
        smartFilter:
          type: boolean
        previouslyMatchedEpisodes:
          type: array
          items:
            type: string
        torrentParams:
          $ref: '#/components/schemas/RSSRuleTorrentParams'
        savePath:
          type: string
          description: Legacy field
        assignedCategory:
          type: string
          description: Legacy field
        addPaused:
          type: boolean
          nullable: true
          description: Legacy field
    RSSArticle:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        torrentURL:
          type: string
        link:
          type: string
        description:
          type: string
        date:
          type: string
          format: date-time
        author:
          type: string
        isRead:
          type: boolean
    RSSFeed:
      type: object
      properties:
        url:
          type: string
          format: uri
        title:
          type: string
        lastBuildDate:
          type: string
        isLoading:
          type: boolean
        hasError:
          type: boolean
        articles:
          type: array
          items:
            $ref: '#/components/schemas/RSSArticle'
    RSSItems:
      type: object
      additionalProperties:
        oneOf:
        - $ref: '#/components/schemas/RSSFeed'
        - $ref: '#/components/schemas/RSSItems'
      description: Map of RSS feeds and folders (recursive structure)
  parameters:
    instanceID:
      name: instanceID
      in: path
      required: true
      schema:
        type: integer
        minimum: 0
      description: qBittorrent instance ID. 0 is the unified scope on the endpoints that support it.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication
    ApiKeyQuery:
      type: apiKey
      in: query
      name: apikey
      description: API key via query parameter for external webhook integrations
    SessionAuth:
      type: apiKey
      in: cookie
      name: qui_user_session
      description: 'Browser session cookie set by the qui web UI. POST, PUT, PATCH, and DELETE

        requests authenticated by this cookie must also send an `X-Requested-With`

        header. Other clients should use an API key.

        '