openapi.yaml

openapi: 3.1.0
info:
  title: qui API
  description: qui API for managing multiple qBittorrent instances
  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: []

paths:
  /api/auth/setup:
    post:
      tags:
        - Authentication
      summary: Initial setup
      description: Create the initial admin user (only available before first user is created)
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - username
                - password
              properties:
                username:
                  type: string
                  minLength: 1
                password:
                  type: string
                  minLength: 8
                  writeOnly: true
                  description: Password will be hashed and never returned in responses
      responses:
        '201':
          description: Setup completed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  user:
                    $ref: '#/components/schemas/User'
        '400':
          description: Setup already completed

  /api/auth/login:
    post:
      tags:
        - Authentication
      summary: Login
      description: Authenticate with username and password
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - username
                - password
              properties:
                username:
                  type: string
                password:
                  type: string
                  writeOnly: true
                  description: Password will be hashed and never returned in responses
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  user:
                    $ref: '#/components/schemas/User'
        '401':
          description: Invalid credentials

  /api/auth/check-setup:
    get:
      tags:
        - Authentication
      summary: Check setup status
      description: Check if initial setup is required
      security: []
      responses:
        '200':
          description: Setup status
          content:
            application/json:
              schema:
                type: object
                properties:
                  setupRequired:
                    type: boolean

  /api/auth/logout:
    post:
      tags:
        - Authentication
      summary: Logout
      description: End the current session
      responses:
        '200':
          description: Logged out successfully

  /api/auth/me:
    get:
      tags:
        - Authentication
      summary: Get current user
      description: Get information about the authenticated user
      responses:
        '200':
          description: Current user information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

  /api/auth/change-password:
    put:
      tags:
        - Authentication
      summary: Change password
      description: Change the current user's password
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - currentPassword
                - newPassword
              properties:
                currentPassword:
                  type: string
                  writeOnly: true
                  description: Current password for verification
                newPassword:
                  type: string
                  minLength: 8
                  writeOnly: true
                  description: New password will be hashed and never returned in responses
      responses:
        '200':
          description: Password changed successfully
        '401':
          description: Invalid current password

  /api/api-keys:
    get:
      tags:
        - API Keys
      summary: List API keys
      description: Get all API keys for the current user
      responses:
        '200':
          description: List of API keys
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiKey'
    post:
      tags:
        - API Keys
      summary: Create API key
      description: Generate a new API key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  description: Descriptive name for the API key
      responses:
        '201':
          description: API key created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                  key:
                    type: string
                    description: The API key (only shown once)
                  createdAt:
                    type: string
                    format: date-time
                  message:
                    type: string

  /api/api-keys/{id}:
    delete:
      tags:
        - API Keys
      summary: Delete API key
      description: Revoke an API key
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: API key deleted successfully
        '404':
          description: API key not found

  /api/client-api-keys:
    get:
      tags:
        - Client API Keys
      summary: List client API keys
      description: Get all client API keys for external applications
      responses:
        '200':
          description: List of client API keys
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ClientApiKey'
    post:
      tags:
        - Client API Keys
      summary: Create client API key
      description: Generate a new client API key for external applications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - clientName
                - instanceId
              properties:
                clientName:
                  type: string
                  description: Name of the client application (e.g., "Sonarr")
                instanceId:
                  type: integer
                  description: ID of the qBittorrent instance to proxy to
      responses:
        '201':
          description: Client API key created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  clientName:
                    type: string
                  instanceId:
                    type: integer
                  key:
                    type: string
                    description: The client API key (only shown once)
                  createdAt:
                    type: string
                    format: date-time
                  message:
                    type: string

  /api/client-api-keys/{id}:
    delete:
      tags:
        - Client API Keys
      summary: Delete client API key
      description: Revoke a client API key
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Client API key deleted successfully
        '404':
          description: Client API key not found

  /api/external-programs:
    get:
      tags:
        - External Programs
      summary: List external programs
      description: Get all configured external programs
      responses:
        '200':
          description: List of external programs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ExternalProgram'
    post:
      tags:
        - External Programs
      summary: Create external program
      description: Add a new external program configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - path
              properties:
                name:
                  type: string
                  description: Display name for the external program
                path:
                  type: string
                  description: Path to the executable
                args_template:
                  type: string
                  description: Arguments template with variable substitution ({hash}, {name}, {save_path}, {content_path}, {category}, {tags}, {state}, {size}, {progress})
                enabled:
                  type: boolean
                  default: true
                  description: Whether this program is enabled
                use_terminal:
                  type: boolean
                  default: true
                  description: Whether to launch in a terminal window
                path_mappings:
                  type: array
                  items:
                    $ref: '#/components/schemas/PathMapping'
                  default: []
                  description: Path mappings to convert remote paths to local paths (useful for remote instances)
      responses:
        '201':
          description: External program created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalProgram'
        '409':
          description: A program with this name already exists

  /api/external-programs/{id}:
    put:
      tags:
        - External Programs
      summary: Update external program
      description: Update an external program configuration
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - path
              properties:
                name:
                  type: string
                  description: Display name for the external program
                path:
                  type: string
                  description: Path to the executable
                args_template:
                  type: string
                  description: Arguments template with variable substitution
                enabled:
                  type: boolean
                  description: Whether this program is enabled
                use_terminal:
                  type: boolean
                  description: Whether to launch in a terminal window
                path_mappings:
                  type: array
                  items:
                    $ref: '#/components/schemas/PathMapping'
                  description: Path mappings to convert remote paths to local paths
      responses:
        '200':
          description: External program updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalProgram'
        '404':
          description: External program not found
        '409':
          description: A program with this name already exists
    delete:
      tags:
        - External Programs
      summary: Delete external program
      description: Delete an external program configuration
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: External program deleted successfully
        '404':
          description: External program not found

  /api/external-programs/execute:
    post:
      tags:
        - External Programs
      summary: Execute external program
      description: |
        Execute an external program for one or more torrents.

        The program is launched asynchronously, and this endpoint returns immediately after starting the process.
        The 'success' field in the response indicates whether the program was successfully launched, not whether it completed successfully.

        The program path and arguments are passed through variable substitution where placeholders
        like {hash}, {name}, {save_path}, etc. are replaced with actual torrent metadata.

        Security: On Windows, all arguments are escaped for cmd.exe using ^ before being passed
        to CreateProcess to prevent command injection via malicious torrent names.
        On Unix/Linux, arguments are wrapped in single quotes with proper escaping.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - program_id
                - instance_id
                - hashes
              properties:
                program_id:
                  type: integer
                  description: ID of the external program to execute
                  example: 1
                instance_id:
                  type: integer
                  description: ID of the qBittorrent instance where the torrents are located
                  example: 1
                hashes:
                  type: array
                  items:
                    type: string
                  description: Array of torrent hashes to execute the program for
                  example: ["abc123def456", "789ghi012jkl"]
      responses:
        '200':
          description: Execution results
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        hash:
                          type: string
                        success:
                          type: boolean
                        message:
                          type: string
                        error:
                          type: string
        '400':
          description: Invalid request (missing program_id, instance_id, or hashes; or program is disabled)
        '404':
          description: Program not found
        '500':
          description: Internal server error (failed to get client for instance, failed to retrieve torrent info)

  /proxy/{api-key}/api/v2/torrents/mediainfo:
    get:
      tags:
        - Proxy
      summary: Get MediaInfo via proxy API key
      description: >
        Returns MediaInfo summary text and JSON output for an instance-relative content path using
        a client API key in the proxy path.
      security: []
      parameters:
        - name: api-key
          in: path
          required: true
          schema:
            type: string
          description: Client API key
        - name: contentPath
          in: query
          required: false
          schema:
            type: string
          description: "Canonical instance-relative content path (legacy alias: content_path)"
        - name: content_path
          in: query
          required: false
          schema:
            type: string
          description: Legacy alias for contentPath
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                contentPath:
                  type: string
                  description: Canonical instance-relative content path
                content_path:
                  type: string
                  description: Legacy alias for contentPath
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                contentPath:
                  type: string
                  description: Canonical instance-relative content path
                content_path:
                  type: string
                  description: Legacy alias for contentPath
      responses:
        '200':
          description: MediaInfo summary and JSON
          content:
            application/json:
              schema:
                type: object
                properties:
                  contentPath:
                    type: string
                  summaryTxt:
                    type: string
                  mediaInfoJson:
                    type: object
                    additionalProperties: true
        '400':
          description: Invalid content path
        '401':
          description: Missing or invalid client API key
        '403':
          description: Instance does not have local filesystem access
        '404':
          description: Instance or file not found
        '500':
          description: Internal server error

  /api/arr/instances:
    get:
      tags:
        - ARR Integrations
      summary: List ARR instances
      description: Get all configured Sonarr/Radarr instances
      responses:
        '200':
          description: List of ARR instances
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ArrInstance'
    post:
      tags:
        - ARR Integrations
      summary: Create ARR instance
      description: Add a new Sonarr or Radarr instance configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArrInstanceCreate'
      responses:
        '201':
          description: ARR instance created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrInstance'
        '400':
          description: Invalid request
        '409':
          description: An instance with this URL already exists for this type

  /api/arr/instances/{id}:
    get:
      tags:
        - ARR Integrations
      summary: Get ARR instance
      description: Get a single Sonarr/Radarr instance by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: ARR instance details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrInstance'
        '404':
          description: ARR instance not found
    put:
      tags:
        - ARR Integrations
      summary: Update ARR instance
      description: Update an existing Sonarr/Radarr instance configuration
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArrInstanceUpdate'
      responses:
        '200':
          description: ARR instance updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrInstance'
        '404':
          description: ARR instance not found
        '409':
          description: An instance with this URL already exists for this type
    delete:
      tags:
        - ARR Integrations
      summary: Delete ARR instance
      description: Delete an ARR instance configuration
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: ARR instance deleted successfully
        '404':
          description: ARR instance not found

  /api/arr/instances/{id}/test:
    post:
      tags:
        - ARR Integrations
      summary: Test ARR instance
      description: Test connectivity to an existing ARR instance
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Test result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrTestResponse'
        '404':
          description: ARR instance not found

  /api/arr/test:
    post:
      tags:
        - ARR Integrations
      summary: Test ARR connection
      description: Test connectivity to an ARR instance before saving
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArrTestConnectionRequest'
      responses:
        '200':
          description: Test result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrTestResponse'
        '400':
          description: Invalid request

  /api/arr/resolve:
    post:
      tags:
        - ARR Integrations
      summary: Resolve title to external IDs
      description: Use configured ARR instances to resolve a title to external IDs (IMDb, TMDb, TVDb, TVMaze)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArrResolveRequest'
      responses:
        '200':
          description: Resolved IDs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrResolveResponse'
        '400':
          description: Invalid request
        '500':
          description: Failed to resolve title

  /api/instances:
    get:
      tags:
        - Instances
      summary: List instances
      description: Get all configured qBittorrent instances
      responses:
        '200':
          description: List of instances
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Instance'
    post:
      tags:
        - Instances
      summary: Add instance
      description: Add a new qBittorrent instance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - host
                - username
                - password
              properties:
                name:
                  type: string
                host:
                  type: string
                  format: uri
                username:
                  type: string
                password:
                  type: string
                  writeOnly: true
                  description: Password for qBittorrent instance. Will be encrypted and never returned in responses.
                basicUsername:
                  type: string
                  nullable: true
                  description: Optional basic auth username
                basicPassword:
                  type: string
                  nullable: true
                  writeOnly: true
                  description: Optional basic auth password. Will be encrypted and never returned in responses.
                tlsSkipVerify:
                  type: boolean
                  description: Set to true to disable TLS certificate verification (for trusted self-signed certificates).
                hasLocalFilesystemAccess:
                  type: boolean
                  description: Set to true if qui can access this instance's download paths locally (required for hardlink detection in automations).
                useHardlinks:
                  type: boolean
                  description: Enable hardlink mode for cross-seed operations on this instance.
                hardlinkBaseDir:
                  type: string
                  description: Base directory for hardlink trees when hardlink mode is enabled.
                hardlinkDirPreset:
                  type: string
                  enum: [flat, by-tracker, by-instance]
                  description: Directory organization preset for hardlink mode.
                linkDirName:
                  type: string
                  description: Optional override for the folder name used by the by-instance hardlink/reflink preset.
      responses:
        '201':
          description: Instance created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'

  /api/instances/order:
    put:
      tags:
        - Instances
      summary: Reorder instances
      description: Update the display order for all configured instances. The list must include every instance ID exactly once.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - instanceIds
              properties:
                instanceIds:
                  type: array
                  items:
                    type: integer
                  description: Instance IDs in the desired display order.
      responses:
        '200':
          description: Updated list of instances in the new order
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Instance'
        '400':
          description: Invalid reorder request
        '500':
          description: Failed to persist the new instance order

  /api/instances/{instanceID}:
    put:
      tags:
        - Instances
      summary: Update instance
      description: Update instance configuration
      parameters:
        - $ref: '#/components/parameters/instanceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                host:
                  type: string
                  format: uri
                username:
                  type: string
                password:
                  type: string
                  writeOnly: true
                  description: Password for qBittorrent instance. Optional for updates - only updates if provided and not masked.
                basicUsername:
                  type: string
                  nullable: true
                  description: Optional basic auth username
                basicPassword:
                  type: string
                  nullable: true
                  writeOnly: true
                  description: Optional basic auth password. For updates - provide new password to update, omit field to keep existing, or empty string to remove basic auth.
                tlsSkipVerify:
                  type: boolean
                  description: Set to true to disable TLS certificate verification (for trusted self-signed certificates).
                hasLocalFilesystemAccess:
                  type: boolean
                  description: Set to true if qui can access this instance's download paths locally (required for hardlink detection in automations).
                useHardlinks:
                  type: boolean
                  description: Enable hardlink mode for cross-seed operations on this instance.
                hardlinkBaseDir:
                  type: string
                  description: Base directory for hardlink trees when hardlink mode is enabled.
                hardlinkDirPreset:
                  type: string
                  enum: [flat, by-tracker, by-instance]
                  description: Directory organization preset for hardlink mode.
                linkDirName:
                  type: string
                  description: Optional override for the folder name used by the by-instance hardlink/reflink preset.
      responses:
        '200':
          description: Instance updated
    delete:
      tags:
        - Instances
      summary: Delete instance
      description: Remove a qBittorrent instance
      parameters:
        - $ref: '#/components/parameters/instanceID'
      responses:
        '204':
          description: Instance deleted
        '404':
          description: Instance not found

  /api/instances/{instanceID}/status:
    put:
      tags:
        - Instances
      summary: Update instance status
      description: Enable or disable automatic polling for the specified instance
      parameters:
        - $ref: '#/components/parameters/instanceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - isActive
              properties:
                isActive:
                  type: boolean
                  description: Set to false to pause all automatic connections to the upstream qBittorrent instance.
      responses:
        '200':
          description: Instance status updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
        '404':
          description: Instance not found
        '500':
          description: Failed to update instance status

  /api/instances/{instanceID}/test:
    post:
      tags:
        - Instances
      summary: Test connection
      description: Test connection to a qBittorrent instance
      parameters:
        - $ref: '#/components/parameters/instanceID'
      responses:
        '200':
          description: Connection successful
        '503':
          description: Connection failed

  /api/instances/{instanceID}/app-info:
    get:
      tags:
        - Instances
      summary: Get qBittorrent application info
      description: Get qBittorrent version and build information for an instance
      parameters:
        - $ref: '#/components/parameters/instanceID'
      responses:
        '200':
          description: qBittorrent application information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QBittorrentAppInfo'
        '400':
          description: Invalid instance ID
        '500':
          description: Failed to get qBittorrent application info

  /api/instances/{instanceID}/capabilities:
    get:
      tags:
        - Instances
      summary: Get instance capabilities
      description: Retrieve lightweight capability metadata for a qBittorrent instance.
      parameters:
        - $ref: '#/components/parameters/instanceID'
      responses:
        '200':
          description: Instance capabilities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceCapabilities'
        '400':
          description: Invalid instance ID
        '503':
          description: Instance unavailable

  /api/instances/{instanceID}/getDirectoryContent:
    get:
      tags:
        - Instances
      summary: Get directory contents
      description: Retrieve directory contents from the qBittorrent host filesystem for path autocomplete.
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - in: query
          name: dirPath
          required: true
          schema:
            type: string
          description: The directory path to list contents from
        - in: query
          name: withMetadata
          required: false
          schema:
            type: boolean
            default: false
          description: Include file/folder metadata in response
      responses:
        '200':
          description: Directory contents
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                description: List of file and folder paths in the directory
        '400':
          description: Invalid instance ID or directory path
        '500':
          description: Failed to get directory contents

  /api/instances/{instanceID}/reannounce/activity:
    get:
      tags:
        - Instances
      summary: Get recent tracker reannounce activity
      description: Return the most recent tracker reannounce events for an instance.
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
          required: false
          description: Optional maximum number of events to return.
      responses:
        '200':
          description: Recent reannounce events
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    instanceId:
                      type: integer
                      format: int64
                    hash:
                      type: string
                      description: Torrent hash in lowercase.
                    torrentName:
                      type: string
                      description: Optional torrent name associated with the reannounce event.
                    trackers:
                      type: string
                      description: Optional comma-separated list of problematic tracker domains for this event.
                    outcome:
                      type: string
                      enum:
                        - skipped
                        - failed
                        - succeeded
                    reason:
                      type: string
                      description: Short explanation for the outcome.
                    timestamp:
                      type: string
                      format: date-time
                  required:
                    - instanceId
                    - hash
                    - outcome
                    - timestamp
        '400':
          description: Invalid instance ID

  /api/instances/{instanceID}/reannounce/candidates:
    get:
      tags:
        - Instances
      summary: Get current tracker reannounce candidates
      description: Return torrents that currently fall within the reannounce monitoring scope and have problematic or pending trackers.
      parameters:
        - $ref: '#/components/parameters/instanceID'
      responses:
        '200':
          description: Current reannounce monitoring candidates
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    instanceId:
                      type: integer
                      format: int64
                    hash:
                      type: string
                      description: Torrent hash in lowercase.
                    torrentName:
                      type: string
                      description: Torrent name associated with the candidate.
                    trackers:
                      type: string
                      description: Optional comma-separated list of problematic tracker domains for this torrent.
                    timeActiveSeconds:
                      type: integer
                      format: int64
                      description: Active time for the torrent in seconds.
                    category:
                      type: string
                      description: Torrent category.
                    tags:
                      type: string
                      description: Comma-separated tags as reported by qBittorrent.
                    state:
                      type: string
                      description: Monitoring state for this torrent.
                      enum:
                        - watching
                        - reannouncing
                        - cooldown
                    hasTrackerProblem:
                      type: boolean
                      description: Whether a tracker problem has been detected for this torrent.
                    waitingForInitial:
                      type: boolean
                      description: Whether trackers are still in an initial updating/not contacted state.
                  required:
                    - instanceId
                    - hash
                    - state
                    - hasTrackerProblem
                    - waitingForInitial
        '400':
          description: Invalid instance ID

  /api/instances/{instanceID}/cross-seed/status:
    get:
      tags:
        - Cross-Seed
      summary: Get cross-seed status for instance
      description: Get cross-seed statistics and status for a specific qBittorrent instance
      parameters:
        - $ref: '#/components/parameters/instanceID'
      responses:
        '200':
          description: Cross-seed status for the instance
          content:
            application/json:
              schema:
                type: object
                properties:
                  instance_id:
                    type: integer
                  cross_seeded:
                    type: integer
                    description: Number of torrents that have been cross-seeded
                  pending:
                    type: integer
                    description: Number of torrents pending cross-seed
                  last_cross_seed:
                    type: string
                    format: date-time
                    nullable: true
                    description: Timestamp of last cross-seed operation
        '400':
          description: Invalid instance ID
        '500':
          description: Failed to get cross-seed status

  /api/instances/{instanceID}/torrents:
    get:
      tags:
        - Torrents
      summary: List torrents
      description: Get paginated list of torrents
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - name: page
          in: query
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          schema:
            type: integer
            default: 500
            maximum: 2000
        - name: sort
          in: query
          schema:
            type: string
            enum: [name, size, progress, priority, added_on]
        - name: order
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: desc
        - name: search
          in: query
          schema:
            type: string
        - name: filters
          in: query
          schema:
            type: string
            description: JSON object with filter criteria (`status`, `categories`, `tags`, `excludeTags`, `trackers`)
      responses:
        '200':
          description: Paginated torrent list
          content:
            application/json:
              schema:
                type: object
                properties:
                  torrents:
                    type: array
                    items:
                      $ref: '#/components/schemas/Torrent'
                  total:
                    type: integer
                  page:
                    type: integer
                  limit:
                    type: integer
    post:
      tags:
        - Torrents
      summary: Add torrent
      description: Add a new torrent via file upload or magnet link
      parameters:
        - $ref: '#/components/parameters/instanceID'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                torrentFile:
                  type: string
                  format: binary
                urls:
                  type: array
                  items:
                    type: string
                category:
                  type: string
                tags:
                  type: array
                  items:
                    type: string
                startPaused:
                  type: boolean
                savePath:
                  type: string
      responses:
        '201':
          description: Torrent added successfully


  /api/instances/{instanceID}/torrents/check-duplicates:
    post:
      tags:
        - Torrents
      summary: Check for duplicate torrents
      description: Determine whether any of the provided hashes already exist on the qBittorrent instance. Supports infohash v1 or v2 values.
      parameters:
        - $ref: '#/components/parameters/instanceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - hashes
              properties:
                hashes:
                  type: array
                  description: List of torrent hashes to check. Maximum 512 entries per request.
                  items:
                    type: string
      responses:
        '200':
          description: Existing torrents matching the provided hashes
          content:
            application/json:
              schema:
                type: object
                properties:
                  duplicates:
                    type: array
                    items:
                      $ref: '#/components/schemas/DuplicateTorrentMatch'
        '400':
          description: Invalid request body or too many hashes provided
        '500':
          description: Failed to check duplicates


  /api/instances/{instanceID}/torrents/bulk-action:
    post:
      tags:
        - Torrents
      summary: Bulk torrent action
      description: Perform bulk actions on multiple torrents
      parameters:
        - $ref: '#/components/parameters/instanceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - action
              properties:
                hashes:
                  type: array
                  items:
                    type: string
                  description: Specific torrent hashes to target. Required unless selectAll is true.
                selectAll:
                  type: boolean
                  description: Apply the action to all torrents matching the provided filters.
                filters:
                  type: object
                  description: Filter criteria used when selectAll is true.
                  properties:
                    status:
                      type: array
                      items:
                        type: string
                    categories:
                      type: array
                      items:
                        type: string
                    tags:
                      type: array
                      items:
                        type: string
                    trackers:
                      type: array
                      items:
                        type: string
                search:
                  type: string
                  description: Optional search query applied when selectAll is true.
                excludeHashes:
                  type: array
                  items:
                    type: string
                  description: Hashes to exclude when selectAll is true.
                action:
                  type: string
                  description: Bulk action to perform on the selected torrents.
                  enum:
                    - pause
                    - resume
                    - delete
                    - deleteWithFiles
                    - recheck
                    - reannounce
                    - increasePriority
                    - decreasePriority
                    - topPriority
                    - bottomPriority
                    - addTags
                    - removeTags
                    - setTags
                    - setCategory
                    - toggleAutoTMM
                    - setShareLimit
                    - setUploadLimit
                    - setDownloadLimit
                    - setLocation
                    - editTrackers
                    - addTrackers
                    - removeTrackers
                    - toggleSequentialDownload
                deleteFiles:
                  type: boolean
                  description: Only for delete action
                tags:
                  type: string
                  description: Comma-separated list of tags for tag-related actions.
                category:
                  type: string
                  description: Category name for setCategory action.
                enable:
                  type: boolean
                  description: Enable or disable Automatic Torrent Management for toggleAutoTMM.
                ratioLimit:
                  type: number
                  format: float
                  description: Ratio limit for setShareLimit action.
                seedingTimeLimit:
                  type: integer
                  format: int64
                  description: Seeding time limit (minutes) for setShareLimit action.
                inactiveSeedingTimeLimit:
                  type: integer
                  format: int64
                  description: Inactive seeding time limit (minutes) for setShareLimit action.
                uploadLimit:
                  type: integer
                  format: int64
                  description: Upload speed limit in KB/s for setUploadLimit action.
                downloadLimit:
                  type: integer
                  format: int64
                  description: Download speed limit in KB/s for setDownloadLimit action.
                location:
                  type: string
                  description: Destination path for setLocation action.
                trackerOldURL:
                  type: string
                  description: Existing tracker URL to replace for editTrackers action.
                trackerNewURL:
                  type: string
                  description: Replacement tracker URL for editTrackers action.
                trackerURLs:
                  type: string
                  description: Newline-separated tracker URLs for addTrackers/removeTrackers actions.
      responses:
        '200':
          description: Action performed successfully


  /api/instances/{instanceID}/torrents/{hash}/export:
    get:
      tags:
        - Torrent Details
      summary: Export torrent file
      description: Download the .torrent file for a specific torrent
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - $ref: '#/components/parameters/hash'
      responses:
        '200':
          description: Torrent file
          content:
            application/x-bittorrent:
              schema:
                type: string
                format: binary
        '400':
          description: Invalid request
        '500':
          description: Failed to export torrent

  /api/instances/{instanceID}/torrents/{hash}/properties:
    get:
      tags:
        - Torrent Details
      summary: Get torrent properties
      description: Get detailed properties of a torrent
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - $ref: '#/components/parameters/hash'
      responses:
        '200':
          description: Torrent properties
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TorrentProperties'

  /api/instances/{instanceID}/torrents/{hash}/trackers:
    get:
      tags:
        - Torrent Details
      summary: Get torrent trackers
      description: Get list of trackers for a torrent
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - $ref: '#/components/parameters/hash'
      responses:
        '200':
          description: List of trackers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tracker'
    put:
      tags:
        - Torrent Details
      summary: Edit torrent tracker
      description: Edit a tracker URL for a torrent
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - $ref: '#/components/parameters/hash'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - oldURL
                - newURL
              properties:
                oldURL:
                  type: string
                  description: The current tracker URL to replace
                newURL:
                  type: string
                  description: The new tracker URL
      responses:
        '200':
          description: Tracker edited successfully
        '400':
          description: Invalid request
        '500':
          description: Failed to edit tracker
    post:
      tags:
        - Torrent Details
      summary: Add torrent trackers
      description: Add new trackers to a torrent
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - $ref: '#/components/parameters/hash'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - urls
              properties:
                urls:
                  type: string
                  description: Newline-separated list of tracker URLs to add
      responses:
        '200':
          description: Trackers added successfully
        '400':
          description: Invalid request
        '500':
          description: Failed to add trackers
    delete:
      tags:
        - Torrent Details
      summary: Remove torrent trackers
      description: Remove trackers from a torrent
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - $ref: '#/components/parameters/hash'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - urls
              properties:
                urls:
                  type: string
                  description: Newline-separated list of tracker URLs to remove
      responses:
        '200':
          description: Trackers removed successfully
        '400':
          description: Invalid request
        '500':
          description: Failed to remove trackers

  /api/instances/{instanceID}/torrents/{hash}/webseeds:
    get:
      tags:
        - Torrent Details
      summary: Get torrent web seeds
      description: Get list of web seeds (HTTP sources) for a torrent
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - $ref: '#/components/parameters/hash'
      responses:
        '200':
          description: List of web seeds
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WebSeed'
        '400':
          description: Invalid request
        '500':
          description: Failed to get web seeds

  /api/instances/{instanceID}/torrents/{hash}/files:
    get:
      tags:
        - Torrent Details
      summary: Get torrent files
      description: Get list of files in a torrent
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - $ref: '#/components/parameters/hash'
        - in: query
          name: refresh
          schema:
            type: boolean
          description: Force refresh from qBittorrent instead of serving cached file metadata.
      responses:
        '200':
          description: List of files
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TorrentFile'
    put:
      tags:
        - Torrent Details
      summary: Update torrent file priorities
      description: Adjust the download priority (including do-not-download) for one or more files in a torrent.
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - $ref: '#/components/parameters/hash'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - indices
                - priority
              properties:
                indices:
                  type: array
                  description: File indices to update.
                  minItems: 1
                  items:
                    type: integer
                    minimum: 0
                priority:
                  type: integer
                  description: Desired priority value (0-7, where 0 marks files as do-not-download).
                  minimum: 0
                  maximum: 7
      responses:
        '204':
          description: File priorities updated successfully
        '400':
          description: Invalid request payload or priority
        '409':
          description: Torrent metadata not yet available
        '500':
          description: Failed to update file priorities

  /api/instances/{instanceID}/torrents/{hash}/rename:
    put:
      tags:
        - Torrent Details
      summary: Rename torrent
      description: Update the display name for a torrent
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - $ref: '#/components/parameters/hash'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  description: New name to assign to the torrent
      responses:
        '200':
          description: Torrent renamed successfully
        '400':
          description: Invalid request
        '500':
          description: Failed to rename torrent

  /api/instances/{instanceID}/torrents/{hash}/rename-file:
    put:
      tags:
        - Torrent Details
      summary: Rename torrent file
      description: Rename a specific file within a torrent
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - $ref: '#/components/parameters/hash'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - oldPath
                - newPath
              properties:
                oldPath:
                  type: string
                  description: Existing relative path of the file inside the torrent
                newPath:
                  type: string
                  description: New relative path (including file name) to apply
      responses:
        '200':
          description: Torrent file renamed successfully
        '400':
          description: Invalid request
        '500':
          description: Failed to rename torrent file

  /api/instances/{instanceID}/torrents/{hash}/rename-folder:
    put:
      tags:
        - Torrent Details
      summary: Rename torrent folder
      description: Rename a folder within a torrent
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - $ref: '#/components/parameters/hash'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - oldPath
                - newPath
              properties:
                oldPath:
                  type: string
                  description: Existing folder path relative to the torrent root
                newPath:
                  type: string
                  description: New folder path (relative) to apply
      responses:
        '200':
          description: Torrent folder renamed successfully
        '400':
          description: Invalid request
        '500':
          description: Failed to rename torrent folder

  /api/instances/{instanceID}/torrents/{hash}/peers:
    get:
      tags:
        - Torrent Details
      summary: Get torrent peers
      description: Get list of peers for a torrent
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - $ref: '#/components/parameters/hash'
      responses:
        '200':
          description: List of peers
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    ip:
                      type: string
                    port:
                      type: integer
                    client:
                      type: string
                    progress:
                      type: number
                    dlSpeed:
                      type: integer
                    upSpeed:
                      type: integer
                    downloaded:
                      type: integer
                    uploaded:
                      type: integer
                    connection:
                      type: string
                    flags:
                      type: string
                    flagsDesc:
                      type: string
                    relevance:
                      type: number

  /api/instances/{instanceID}/torrents/add-peers:
    post:
      tags:
        - Torrents
      summary: Add peers to torrents
      description: Add peers to one or more torrents
      parameters:
        - $ref: '#/components/parameters/instanceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - hashes
                - peers
              properties:
                hashes:
                  type: array
                  items:
                    type: string
                  description: List of torrent hashes
                peers:
                  type: array
                  items:
                    type: string
                  description: List of peers in host:port format
      responses:
        '200':
          description: Peers added successfully

  /api/instances/{instanceID}/torrents/ban-peers:
    post:
      tags:
        - Torrents
      summary: Ban peers permanently
      description: Ban peers from connecting to the client
      parameters:
        - $ref: '#/components/parameters/instanceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - peers
              properties:
                peers:
                  type: array
                  items:
                    type: string
                  description: List of peer IPs to ban
      responses:
        '200':
          description: Peers banned successfully

  /api/instances/{instanceID}/torrent-creator:
    post:
      tags:
        - Torrents
      summary: Create torrent
      description: Create a new torrent file from a source path. Requires qBittorrent v5.0.0 or later.
      parameters:
        - $ref: '#/components/parameters/instanceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - sourcePath
              properties:
                sourcePath:
                  type: string
                  description: Path to the source file or directory
                torrentFilePath:
                  type: string
                  description: Custom path for saving the torrent file
                private:
                  type: boolean
                  description: Create a private torrent
                format:
                  type: string
                  enum: [v1, v2, hybrid]
                  description: Torrent format
                optimizeAlignment:
                  type: boolean
                  description: Optimize piece alignment
                paddedFileSizeLimit:
                  type: integer
                  description: Padded file size limit
                pieceSize:
                  type: integer
                  description: Piece size in bytes
                comment:
                  type: string
                  description: Comment for the torrent
                source:
                  type: string
                  description: Source string for the torrent
                trackers:
                  type: array
                  items:
                    type: string
                  description: List of tracker URLs
                urlSeeds:
                  type: array
                  items:
                    type: string
                  description: List of URL seeds
                startSeeding:
                  type: boolean
                  description: Start seeding after creation
      responses:
        '201':
          description: Torrent creation task created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  taskID:
                    type: string
                  sourcePath:
                    type: string
                  status:
                    type: string
                  timeAdded:
                    type: string
        '400':
          description: Invalid request or unsupported qBittorrent version
        '409':
          description: Too many active torrent creation tasks

  /api/instances/{instanceID}/torrent-creator/status:
    get:
      tags:
        - Torrents
      summary: Get torrent creation status
      description: Get status of torrent creation tasks. Query parameter taskID can be used to filter by specific task.
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - name: taskID
          in: query
          schema:
            type: string
          description: Optional task ID to filter by
      responses:
        '200':
          description: List of torrent creation tasks
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    taskID:
                      type: string
                    sourcePath:
                      type: string
                    torrentFilePath:
                      type: string
                    pieceSize:
                      type: integer
                    private:
                      type: boolean
                    format:
                      type: string
                    status:
                      type: string
                    timeAdded:
                      type: string
                    timeStarted:
                      type: string
                    timeFinished:
                      type: string
                    progress:
                      type: number
                    errorMessage:
                      type: string
        '400':
          description: Invalid request or unsupported qBittorrent version
        '404':
          description: Torrent creation task not found

  /api/instances/{instanceID}/torrent-creator/count:
    get:
      tags:
        - Torrents
      summary: Get active torrent creation task count
      description: Get the number of active (running or queued) torrent creation tasks.
      parameters:
        - $ref: '#/components/parameters/instanceID'
      responses:
        '200':
          description: Active torrent creation task count
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Number of active torrent creation tasks
        '400':
          description: Invalid instance ID

  /api/instances/{instanceID}/torrent-creator/{taskID}:
    delete:
      tags:
        - Torrents
      summary: Delete torrent creation task
      description: Delete a torrent creation task
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - name: taskID
          in: path
          required: true
          schema:
            type: string
          description: Task ID to delete
      responses:
        '200':
          description: Torrent creation task deleted successfully
        '400':
          description: Invalid request or unsupported qBittorrent version
        '404':
          description: Torrent creation task not found

  /api/instances/{instanceID}/torrent-creator/{taskID}/file:
    get:
      tags:
        - Torrents
      summary: Download created torrent file
      description: Download the torrent file for a completed torrent creation task
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - name: taskID
          in: path
          required: true
          schema:
            type: string
          description: Task ID of the completed torrent
      responses:
        '200':
          description: Torrent file downloaded successfully
          content:
            application/x-bittorrent:
              schema:
                type: string
                format: binary
        '400':
          description: Invalid request or unsupported qBittorrent version
        '404':
          description: Torrent creation task not found
        '409':
          description: Torrent creation is still in progress or failed

  /api/instances/{instanceID}/categories:
    get:
      tags:
        - Categories
      summary: List categories
      description: Get all categories
      parameters:
        - $ref: '#/components/parameters/instanceID'
      responses:
        '200':
          description: List of categories
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Category'
    post:
      tags:
        - Categories
      summary: Create category
      description: Create a new category
      parameters:
        - $ref: '#/components/parameters/instanceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                savePath:
                  type: string
      responses:
        '201':
          description: Category created
    put:
      tags:
        - Categories
      summary: Edit category
      description: Edit an existing category
      parameters:
        - $ref: '#/components/parameters/instanceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                savePath:
                  type: string
      responses:
        '200':
          description: Category updated
    delete:
      tags:
        - Categories
      summary: Delete categories
      description: Delete one or more categories
      parameters:
        - $ref: '#/components/parameters/instanceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - categories
              properties:
                categories:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Categories deleted

  /api/instances/{instanceID}/tags:
    get:
      tags:
        - Tags
      summary: List tags
      description: Get all tags
      parameters:
        - $ref: '#/components/parameters/instanceID'
      responses:
        '200':
          description: List of tags
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
    post:
      tags:
        - Tags
      summary: Create tags
      description: Create new tags
      parameters:
        - $ref: '#/components/parameters/instanceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - tags
              properties:
                tags:
                  type: array
                  items:
                    type: string
      responses:
        '201':
          description: Tags created
    delete:
      tags:
        - Tags
      summary: Delete tags
      description: Delete one or more tags
      parameters:
        - $ref: '#/components/parameters/instanceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - tags
              properties:
                tags:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Tags deleted

  /api/instances/{instanceID}/trackers:
    get:
      tags:
        - Trackers
      summary: List active trackers
      description: Get active tracker domains and representative tracker URLs for an instance
      parameters:
        - $ref: '#/components/parameters/instanceID'
      responses:
        '200':
          description: Active tracker domains mapped to a tracker URL
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
        '400':
          description: Invalid instance ID
        '500':
          description: Failed to get active trackers

  /api/instances/{instanceID}/preferences:
    get:
      tags:
        - Instances
      summary: Get instance preferences
      description: Get qBittorrent instance preferences/settings
      parameters:
        - $ref: '#/components/parameters/instanceID'
      responses:
        '200':
          description: Instance preferences
          content:
            application/json:
              schema:
                type: object
                description: qBittorrent preferences object with various settings
    patch:
      tags:
        - Instances
      summary: Update instance preferences
      description: Update qBittorrent instance preferences/settings
      parameters:
        - $ref: '#/components/parameters/instanceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Partial preferences object with settings to update
      responses:
        '200':
          description: Preferences updated successfully

  /api/instances/{instanceID}/alternative-speed-limits:
    get:
      tags:
        - Instances
      summary: Get alternative speed limits status
      description: Get current status of alternative speed limits (turtle mode)
      parameters:
        - $ref: '#/components/parameters/instanceID'
      responses:
        '200':
          description: Alternative speed limits status
          content:
            application/json:
              schema:
                type: object
                properties:
                  enabled:
                    type: boolean
                    description: Whether alternative speed limits are currently enabled

  /api/instances/{instanceID}/alternative-speed-limits/toggle:
    post:
      tags:
        - Instances
      summary: Toggle alternative speed limits
      description: Toggle alternative speed limits (turtle mode) on/off
      parameters:
        - $ref: '#/components/parameters/instanceID'
      responses:
        '200':
          description: Alternative speed limits toggled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  enabled:
                    type: boolean
                    description: New status of alternative speed limits

  /api/license/activate:
    post:
      tags:
        - Licenses
      summary: Activate license
      description: Activate a license key and store it for the current user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - licenseKey
              properties:
                licenseKey:
                  type: string
      responses:
        '200':
          description: License activated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid:
                    type: boolean
                  productName:
                    type: string
                  expiresAt:
                    type: string
                    format: date-time
                  message:
                    type: string
                  error:
                    type: string
                    nullable: true
        '400':
          description: Invalid request payload
        '403':
          description: License activation failed

  /api/license/validate:
    post:
      tags:
        - Licenses
      summary: Validate license
      description: Validate a license key and ensure it remains active
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - licenseKey
              properties:
                licenseKey:
                  type: string
      responses:
        '200':
          description: License validated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid:
                    type: boolean
                  productName:
                    type: string
                  expiresAt:
                    type: string
                    format: date-time
                  message:
                    type: string
                  error:
                    type: string
                    nullable: true
        '400':
          description: Invalid request payload
        '403':
          description: License validation failed
        '404':
          description: License not found

  /api/license/licensed:
    get:
      tags:
        - Licenses
      summary: Check premium access
      description: Check if any active licenses grant premium access
      responses:
        '200':
          description: Premium access status
          content:
            application/json:
              schema:
                type: object
                properties:
                  hasPremiumAccess:
                    type: boolean

  /api/license/licenses:
    get:
      tags:
        - Licenses
      summary: List licenses
      description: List all stored licenses
      responses:
        '200':
          description: Licenses retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    licenseKey:
                      type: string
                    productName:
                      type: string
                    status:
                      type: string
                    createdAt:
                      type: string
                      format: date-time

  /api/license/{licenseKey}:
    delete:
      tags:
        - Licenses
      summary: Delete license
      description: Remove a stored license
      parameters:
        - name: licenseKey
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: License deleted successfully
        '400':
          description: Invalid license key

  /api/license/refresh:
    post:
      tags:
        - Licenses
      summary: Refresh licenses
      description: Refresh all stored licenses from the licensing service
      responses:
        '200':
          description: Licenses refreshed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '500':
          description: Failed to refresh licenses

  /api/torrents/cross-instance:
    get:
      tags:
        - Torrents
      summary: List torrents across all instances
      description: Get paginated list of torrents from all instances (primarily used for cross-seed filtering)
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          schema:
            type: integer
            default: 500
            maximum: 2000
        - name: sort
          in: query
          schema:
            type: string
            enum: [name, size, progress, priority, added_on, instance]
        - name: order
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: desc
        - name: search
          in: query
          schema:
            type: string
        - name: filters
          in: query
          required: true
          schema:
            type: string
            description: |
              JSON-encoded filter options. Must include the `expr` field for cross-instance filtering.
              See CrossInstanceFilterOptions schema for structure details.
            example: '{"expr":"Hash == \"abcd1234\" || Hash == \"efgh5678\""}'
      responses:
        '200':
          description: Paginated torrent list from all instances
          content:
            application/json:
              schema:
                type: object
                properties:
                  cross_instance_torrents:
                    type: array
                    items:
                      allOf:
                        - $ref: '#/components/schemas/Torrent'
                        - type: object
                          properties:
                            instance_id:
                              type: integer
                              description: ID of the instance this torrent belongs to
                            instance_name:
                              type: string
                              description: Name of the instance this torrent belongs to
                  total:
                    type: integer
                  hasMore:
                    type: boolean
                  isCrossInstance:
                    type: boolean
                    default: true
                  partialResults:
                    type: boolean
                    description: Indicates if some instances failed to respond
        '400':
          description: Missing or invalid filters parameter
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Expression filter is required for cross-instance filtering"
        '500':
          description: Failed to get cross-instance torrents

  /api/tracker-icons:
    get:
      tags:
        - Tracker Icons
      summary: List tracker icons
      description: Retrieve cached tracker favicons as data URLs keyed by tracker hostname
      responses:
        '200':
          description: Cached tracker icons
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                  description: Base64-encoded PNG data URL for the tracker favicon
        '500':
          description: Failed to list tracker icons
  /api/cross-seed/settings:
    get:
      tags:
        - Cross-Seed
      summary: Get cross-seed automation settings
      description: Retrieve the current automation configuration for cross-seeding
      responses:
        '200':
          description: Current automation settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrossSeedAutomationSettings'
        '500':
          description: Failed to load automation settings
    put:
      tags:
        - Cross-Seed
      summary: Update cross-seed automation settings
      description: Persist a new automation schedule and cross-seed preferences
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrossSeedAutomationSettings'
      responses:
        '200':
          description: Updated automation settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrossSeedAutomationSettings'
        '400':
          description: Invalid request body
        '500':
          description: Failed to update automation settings
    patch:
      tags:
        - Cross-Seed
      summary: Patch cross-seed automation settings
      description: Partially update automation, completion, or global cross-seed settings without overwriting unspecified fields
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrossSeedAutomationSettingsPatch'
      responses:
        '200':
          description: Updated automation settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrossSeedAutomationSettings'
        '400':
          description: Invalid request body
        '500':
          description: Failed to update automation settings

  /api/cross-seed/status:
    get:
      tags:
        - Cross-Seed
      summary: Get cross-seed automation status
      description: Returns scheduler state, last run information, and next scheduled run
      responses:
        '200':
          description: Current automation status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrossSeedAutomationStatus'
        '500':
          description: Failed to load automation status

  /api/cross-seed/runs:
    get:
      tags:
        - Cross-Seed
      summary: List cross-seed automation runs
      description: Returns the most recent automation runs
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
          description: Maximum number of runs to return
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
          description: Offset for pagination
      responses:
        '200':
          description: Automation run history
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CrossSeedRun'
        '500':
          description: Failed to load automation runs

  /api/cross-seed/run:
    post:
      tags:
        - Cross-Seed
      summary: Trigger cross-seed automation run
      description: Starts an on-demand automation pass
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrossSeedRunRequest'
      responses:
        '202':
          description: Automation run started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrossSeedRun'
        '400':
          description: Invalid request body
        '409':
          description: Automation is already running
        '500':
          description: Failed to trigger automation run

  /api/cross-seed/search/settings:
    get:
      tags:
        - Cross-Seed
      summary: Get seeded torrent search settings
      description: Returns the persisted defaults used by Seeded Torrent Search runs.
      responses:
        '200':
          description: Current seeded search settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrossSeedSearchSettings'
        '500':
          description: Failed to load search settings
    patch:
      tags:
        - Cross-Seed
      summary: Update seeded torrent search settings
      description: Persists default filters and timing for Seeded Torrent Search runs.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrossSeedSearchSettingsPatch'
      responses:
        '200':
          description: Updated seeded search settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrossSeedSearchSettings'
        '400':
          description: Invalid request body
        '500':
          description: Failed to update search settings

  /api/cross-seed/search/run:
    post:
      tags:
        - Cross-Seed
      summary: Start a cross-seed search run
      description: Starts a new cross-seed search automation run for the specified instance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - instanceId
              properties:
                instanceId:
                  type: integer
                  description: qBittorrent instance ID
                categories:
                  type: array
                  items:
                    type: string
                  description: Filter torrents by categories
                tags:
                  type: array
                  items:
                    type: string
                  description: Filter torrents by tags
                intervalSeconds:
                  type: integer
                  description: Interval between processing torrents in seconds
                indexerIds:
                  type: array
                  items:
                    type: integer
                  description: Specific indexers to search
                cooldownMinutes:
                  type: integer
                  description: Cooldown period between searches for the same torrent
      responses:
        '200':
          description: Search run started
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  instance_id:
                    type: integer
                  status:
                    type: string
                  started_at:
                    type: string
                    format: date-time
        '400':
          description: Invalid request body
        '500':
          description: Failed to start search run

  /api/cross-seed/search/run/cancel:
    post:
      tags:
        - Cross-Seed
      summary: Cancel running search
      description: Cancels the currently running cross-seed search automation
      responses:
        '204':
          description: Search run cancelled successfully

  /api/cross-seed/search/status:
    get:
      tags:
        - Cross-Seed
      summary: Get search run status
      description: Returns the current status of the cross-seed search automation
      responses:
        '200':
          description: Current search run status
          content:
            application/json:
              schema:
                type: object
                properties:
                  running:
                    type: boolean
                  current_run:
                    type: object
                    nullable: true
        '500':
          description: Failed to get search run status

  /api/cross-seed/search/runs:
    get:
      tags:
        - Cross-Seed
      summary: List search run history
      description: Returns the history of cross-seed search automation runs for an instance
      parameters:
        - name: instanceId
          in: query
          required: true
          schema:
            type: integer
          description: Instance ID to get runs for
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 25
            maximum: 200
          description: Maximum number of runs to return
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: Number of runs to skip
      responses:
        '200':
          description: List of search runs
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '400':
          description: Invalid query parameters
        '500':
          description: Failed to list search runs

  /api/cross-seed/completion/{instanceId}:
    get:
      tags:
        - Cross-Seed
      summary: Get per-instance completion settings
      description: Returns the cross-seed completion settings for a specific qBittorrent instance. These settings control automatic cross-seed searches when torrents complete on this instance.
      parameters:
        - name: instanceId
          in: path
          required: true
          schema:
            type: integer
          description: qBittorrent instance ID
      responses:
        '200':
          description: Instance completion settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceCrossSeedCompletionSettings'
        '400':
          description: Invalid instance ID
        '500':
          description: Failed to load completion settings
    put:
      tags:
        - Cross-Seed
      summary: Update per-instance completion settings
      description: Updates the cross-seed completion settings for a specific qBittorrent instance. These settings control automatic cross-seed searches when torrents complete on this instance.
      parameters:
        - name: instanceId
          in: path
          required: true
          schema:
            type: integer
          description: qBittorrent instance ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstanceCrossSeedCompletionSettingsRequest'
      responses:
        '200':
          description: Updated instance completion settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceCrossSeedCompletionSettings'
        '400':
          description: Invalid instance ID or request body
        '500':
          description: Failed to save completion settings
        '503':
          description: Completion settings store not configured

  /api/cross-seed/webhook/check:
    post:
      tags:
        - Cross-Seed
      summary: Check if a release can be cross-seeded (autobrr webhook)
      description: |
        Accepts release metadata from autobrr and checks if matching torrents exist on the requested instances (or all instances when no list is provided). The HTTP status describes whether the match is ready:
        * `200 OK` – at least one matching torrent is fully downloaded and ready for cross-seeding
        * `202 Accepted` – matching torrents exist but the data is still downloading; retry `/check` until it returns `200` (ready) or `404`
        * `404 Not Found` – no matches exist (recommendation `skip`)
        This endpoint is designed for autobrr filter external webhooks. When `instanceIds` is omitted or empty, qui will search every configured instance. Provide a subset of IDs to restrict the scan.
      parameters:
        - name: apikey
          in: query
          required: false
          schema:
            type: string
          description: API key (prefer X-API-Key header; query supported for autobrr webhook).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - torrentName
              properties:
                torrentName:
                  type: string
                  description: Release name as announced (parsed using rls library to extract metadata)
                  example: "That.Movie.2025.1080p.BluRay.x264-GROUP"
                instanceIds:
                  type: array
                  items:
                    type: integer
                  description: Optional list of qBittorrent instance IDs to consider. When omitted or empty, qui searches all configured instances.
                  example: [1, 2, 3]
                size:
                  type: integer
                  format: uint64
                  description: Total torrent size in bytes (optional - enables size validation when provided)
                findIndividualEpisodes:
                  type: boolean
                  description: Optional override for matching season packs vs episodes. Defaults to the Cross-Seed automation setting when omitted.
      responses:
        '200':
          description: Webhook check completed successfully with one or more matches
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrossSeedWebhookCheckResponse'
        '202':
          description: Matches exist but torrents are still downloading (retry until 200 OK). The body mirrors the 200 response to show pending matches.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrossSeedWebhookCheckResponse'
        '404':
          description: No cross-seed matches found across the targeted instances, or no instances were available (empty matches array and canCrossSeed=false with recommendation="skip")
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrossSeedWebhookCheckResponse'
        '400':
          description: Invalid request body
        '500':
          description: Failed to check webhook

  /api/cross-seed/apply:
    post:
      tags:
        - Cross-Seed
      summary: Add a cross-seed torrent provided by autobrr
      description: Accepts a torrent file from autobrr, matches it against the requested instances, and adds it with alignment wherever a complete match exists. When `instanceIds` is omitted or empty, qui attempts to inject the torrent into every configured instance that has a match.
      parameters:
        - name: apikey
          in: query
          required: false
          schema:
            type: string
          description: API key (prefer X-API-Key header; query supported for autobrr).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - torrentData
              properties:
                torrentData:
                  type: string
                  description: Base64-encoded torrent file provided by autobrr (for example, using the TorrentDataRawBytes macro piped through toString|b64enc or toJson)
                instanceIds:
                  type: array
                  items:
                    type: integer
                  description: Optional list of target instance IDs. When omitted or empty, qui attempts to cross-seed into any instance that has a complete match.
                  example: [1, 2]
                category:
                  type: string
                  description: Category to apply when adding the torrent
                tags:
                  type: array
                  items:
                    type: string
                ignorePatterns:
                  type: array
                  items:
                    type: string
                startPaused:
                  type: boolean
                skipIfExists:
                  type: boolean
                findIndividualEpisodes:
                  type: boolean
                indexerName:
                  type: string
                  description: Indexer display name (e.g., "TorrentDB"). Only used when "Use indexer name as category" mode is enabled; ignored otherwise. Webhook applies cannot derive the indexer from the torrent file, so this field is required for that mode.
      responses:
        '200':
          description: Torrent processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrossSeedResponse'
        '400':
          description: Invalid request or no matching torrents found
        '500':
          description: Failed to process autobrr apply request

  /api/cross-seed/torrents/{instanceID}/{hash}/analyze:
    get:
      tags:
        - Cross-Seed
      summary: Analyze torrent for cross-seed search
      description: Analyzes a torrent and returns information needed for cross-seed searching
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - $ref: '#/components/parameters/hash'
      responses:
        '200':
          description: Torrent analysis result
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                  size_bytes:
                    type: integer
                  content_path:
                    type: string
                  num_files:
                    type: integer
        '400':
          description: Invalid parameters
        '500':
          description: Failed to analyze torrent

  /api/cross-seed/torrents/{instanceID}/{hash}/async-status:
    get:
      tags:
        - Cross-Seed
      summary: Get async filtering status
      description: Returns the current async filtering progress for a torrent, including whether content filtering has completed
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - $ref: '#/components/parameters/hash'
      responses:
        '200':
          description: Current async filtering state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncIndexerFilteringState'
        '400':
          description: Invalid parameters
        '500':
          description: Failed to get filtering status

  /api/cross-seed/torrents/{instanceID}/{hash}/search:
    post:
      tags:
        - Cross-Seed
      summary: Search cross-seed candidates for a torrent
      description: Query configured Torznab indexers for releases matching an existing torrent
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - $ref: '#/components/parameters/hash'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrossSeedTorrentSearchRequest'
      responses:
        '200':
          description: Matching releases were found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrossSeedTorrentSearchResponse'
        '400':
          description: Invalid request parameters
        '500':
          description: Failed to search indexers

  /api/cross-seed/torrents/{instanceID}/{hash}/apply:
    post:
      tags:
        - Cross-Seed
      summary: Add torrents found via cross-seed search
      description: Downloads selected results and queues them for cross-seeding on the specified instance
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - $ref: '#/components/parameters/hash'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrossSeedApplyRequest'
      responses:
        '200':
          description: Add operation completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrossSeedApplyResponse'
        '400':
          description: Invalid request body
        '500':
          description: Failed to add torrents

  /api/log-settings:
    get:
      tags:
        - System
      summary: Get log settings
      description: Get the current log configuration including level, file path, and rotation settings
      responses:
        '200':
          description: Current log settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogSettings'
    put:
      tags:
        - System
      summary: Update log settings
      description: Update log configuration. Changes are applied immediately.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LogSettingsUpdate'
      responses:
        '200':
          description: Updated log settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogSettings'
        '400':
          description: Invalid settings or attempting to modify locked fields

  /api/log-exclusions:
    get:
      tags:
        - System
      summary: Get log exclusions
      description: Get the list of muted log message patterns
      responses:
        '200':
          description: Current log exclusions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogExclusions'
    put:
      tags:
        - System
      summary: Update log exclusions
      description: Replace the list of muted log message patterns
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LogExclusionsInput'
      responses:
        '200':
          description: Updated log exclusions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogExclusions'

  /api/logs/stream:
    get:
      tags:
        - System
      summary: Stream live logs
      description: Server-Sent Events endpoint for streaming live log lines. Sends initial history (configurable via limit parameter) then streams new log lines in real-time.
      parameters:
        - name: limit
          in: query
          description: Number of historical log lines to send initially (default 1000)
          schema:
            type: integer
            default: 1000
      responses:
        '200':
          description: SSE stream of log lines
          content:
            text/event-stream:
              schema:
                type: string
                description: Each message is a log line in SSE format

  /api/version/latest:
    get:
      tags:
        - System
      summary: Check for latest version
      description: Check if a newer version of qui is available
      responses:
        '200':
          description: Update available - newer version found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LatestVersionResponse'
        '204':
          description: No update available - current version is latest

  /api/instances/{instanceID}/backups/import:
    post:
      tags:
        - Backups
      summary: Import backup manifest
      description: Import a backup manifest file to create a new backup run record. This allows restoring backup metadata from a previously exported manifest.
      parameters:
        - $ref: '#/components/parameters/instanceID'
      requestBody:
        description: Backup archive or manifest file to import. Provide either an archive (zip, tar.gz, tar.zst, tar.br, tar.xz, tar) or a JSON manifest file.
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                archive:
                  type: string
                  format: binary
                  description: Compressed backup archive (zip, tar.gz, tar.zst, tar.br, tar.xz, tar) containing manifest.json and torrent files
                manifest:
                  type: string
                  format: binary
                  description: JSON manifest file exported from a backup run
      responses:
        '201':
          description: Manifest imported successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackupRun'
        '400':
          description: Invalid request - must provide either archive or manifest file, invalid instance ID, or unsupported archive format
        '500':
          description: Failed to import manifest

  /api/instances/{instanceID}/backups/runs/{runId}/restore/preview:
    post:
      tags:
        - Backups
      summary: Preview restore plan
      description: Build a restore plan for the specified backup run without applying any changes.
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - name: runId
          in: path
          required: true
          schema:
            type: integer
          description: Backup run ID
      requestBody:
        description: Restore options
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                mode:
                  type: string
                  description: Restore mode
                  enum:
                    - incremental
                    - overwrite
                    - complete
                excludeHashes:
                  type: array
                  items:
                    type: string
                  description: Torrent hashes to exclude from the generated plan.
                startPaused:
                  type: boolean
                  description: Start restored torrents paused. Defaults to true.
                skipHashCheck:
                  type: boolean
                  description: Skip re-checking the restored torrent data. Defaults to false.
                autoResumeVerified:
                  type: boolean
                  description: Automatically resume torrents once qBittorrent reports them as fully verified. Defaults to true when skip recheck is enabled.
      responses:
        '200':
          description: Restore plan generated successfully
          content:
            application/json:
              schema:
                type: object
                description: Restore plan payload
        '400':
          description: Invalid request payload
        '404':
          description: Backup run not found
        '500':
          description: Failed to build restore plan

  /api/instances/{instanceID}/backups/runs/{runId}/restore:
    post:
      tags:
        - Backups
      summary: Execute restore
      description: Execute the restore plan for the specified backup run.
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - name: runId
          in: path
          required: true
          schema:
            type: integer
          description: Backup run ID
      requestBody:
        description: Restore execution options
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - mode
              properties:
                mode:
                  type: string
                  description: Restore mode
                  enum:
                    - incremental
                    - overwrite
                    - complete
                dryRun:
                  type: boolean
                  description: When true, no changes are applied and the plan is returned.
                excludeHashes:
                  type: array
                  items:
                    type: string
                  description: Torrent hashes to exclude from the restore plan and execution.
                startPaused:
                  type: boolean
                  description: Start restored torrents paused. Defaults to true.
                skipHashCheck:
                  type: boolean
                  description: Skip re-checking the restored torrent data. Defaults to false.
                autoResumeVerified:
                  type: boolean
                  description: Automatically resume torrents once qBittorrent reports them as fully verified. Defaults to true when skip recheck is enabled.
      responses:
        '200':
          description: Restore executed successfully
          content:
            application/json:
              schema:
                type: object
                description: Restore result payload
        '400':
          description: Invalid request payload
        '404':
          description: Backup run not found
        '500':
          description: Failed to execute restore

  /api/instances/{instanceID}/backups/runs/{runId}/download:
    get:
      tags:
        - Backups
      summary: Download backup archive
      description: Download the backup archive for the specified backup run in the requested format.
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - name: runId
          in: path
          required: true
          schema:
            type: integer
          description: Backup run ID
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum:
              - zip
              - tar.gz
              - tar.zst
              - tar.br
              - tar.xz
              - tar
            default: zip
          description: Archive format to download. Defaults to zip.
      responses:
        '200':
          description: Backup archive downloaded successfully
          content:
            application/zip:
              schema:
                type: string
                format: binary
                description: ZIP archive containing the backup
            application/gzip:
              schema:
                type: string
                format: binary
                description: GZIP compressed TAR archive
            application/zstd:
              schema:
                type: string
                format: binary
                description: Zstandard compressed TAR archive
            application/x-brotli:
              schema:
                type: string
                format: binary
                description: Brotli compressed TAR archive
            application/x-xz:
              schema:
                type: string
                format: binary
                description: XZ compressed TAR archive
            application/x-tar:
              schema:
                type: string
                format: binary
                description: Uncompressed TAR archive
        '400':
          description: Invalid instance ID, run ID, or format parameter
        '404':
          description: Backup run not found or not available for download
        '500':
          description: Failed to generate backup archive

  /api/instances/{instanceID}/backups/runs/{runId}/items/{torrentHash}/download:
    get:
      tags:
        - Backups
      summary: Download torrent file from backup
      description: Download a specific torrent file from the backup archive.
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - name: runId
          in: path
          required: true
          schema:
            type: integer
          description: Backup run ID
        - name: torrentHash
          in: path
          required: true
          schema:
            type: string
          description: Torrent hash
      responses:
        '200':
          description: Torrent file downloaded successfully
          content:
            application/x-bittorrent:
              schema:
                type: string
                format: binary
                description: Torrent file
        '400':
          description: Invalid instance ID, run ID, or torrent hash
        '404':
          description: Backup run or torrent not found
        '500':
          description: Failed to retrieve torrent file

  # Orphan File Scanning
  /api/instances/{instanceID}/orphan-scan/settings:
    get:
      tags:
        - Orphan Scan
      summary: Get orphan scan settings
      description: Get orphan file scanning settings for an instance. Requires local filesystem access.
      parameters:
        - $ref: '#/components/parameters/instanceID'
      responses:
        '200':
          description: Orphan scan settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrphanScanSettings'
        '403':
          description: Instance does not have local filesystem access enabled
        '404':
          description: Instance not found
    put:
      tags:
        - Orphan Scan
      summary: Update orphan scan settings
      description: Update orphan file scanning settings for an instance. Requires local filesystem access.
      parameters:
        - $ref: '#/components/parameters/instanceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrphanScanSettingsUpdate'
      responses:
        '200':
          description: Settings updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrphanScanSettings'
        '400':
          description: Invalid settings (e.g., non-absolute ignore paths)
        '403':
          description: Instance does not have local filesystem access enabled
        '404':
          description: Instance not found

  /api/instances/{instanceID}/orphan-scan/scan:
    post:
      tags:
        - Orphan Scan
      summary: Trigger orphan scan
      description: Start a manual orphan file scan for an instance. Returns immediately with the run ID.
      parameters:
        - $ref: '#/components/parameters/instanceID'
      responses:
        '202':
          description: Scan started
          content:
            application/json:
              schema:
                type: object
                properties:
                  runId:
                    type: integer
                    format: int64
                    description: ID of the created scan run
        '403':
          description: Instance does not have local filesystem access enabled
        '404':
          description: Instance not found
        '409':
          description: A scan is already in progress for this instance

  /api/instances/{instanceID}/orphan-scan/runs:
    get:
      tags:
        - Orphan Scan
      summary: List orphan scan runs
      description: Get recent orphan scan runs for an instance. Requires local filesystem access.
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          description: Maximum number of runs to return
      responses:
        '200':
          description: List of scan runs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrphanScanRun'
        '403':
          description: Instance does not have local filesystem access enabled
        '404':
          description: Instance not found

  /api/instances/{instanceID}/orphan-scan/runs/{runID}:
    get:
      tags:
        - Orphan Scan
      summary: Get orphan scan run
      description: Get details of a specific scan run including the list of orphan files found. Requires local filesystem access.
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - name: runID
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Scan run ID
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
          description: Maximum number of files to return
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Offset for pagination
      responses:
        '200':
          description: Scan run with files
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrphanScanRunWithFiles'
        '403':
          description: Instance does not have local filesystem access enabled
        '404':
          description: Run not found
    delete:
      tags:
        - Orphan Scan
      summary: Cancel orphan scan run
      description: Cancel a pending, scanning, or preview_ready run. Cannot cancel runs that are actively deleting. Requires local filesystem access.
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - name: runID
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Scan run ID
      responses:
        '200':
          description: Run canceled
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "canceled"
        '400':
          description: Run already finished
        '403':
          description: Instance does not have local filesystem access enabled
        '404':
          description: Run not found
        '409':
          description: Cannot cancel run while deletion is in progress

  /api/instances/{instanceID}/orphan-scan/runs/{runID}/confirm:
    post:
      tags:
        - Orphan Scan
      summary: Confirm orphan file deletion
      description: Confirm deletion of orphan files from a preview_ready run. This initiates the actual file deletion. Requires local filesystem access.
      parameters:
        - $ref: '#/components/parameters/instanceID'
        - name: runID
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Scan run ID
      responses:
        '202':
          description: Deletion started
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "deleting"
        '400':
          description: Run is not in preview_ready status
        '409':
          description: A scan or deletion is already in progress for this instance
        '403':
          description: Instance does not have local filesystem access enabled
        '404':
          description: Run not found

  /health:
    get:
      tags:
        - System
      summary: Health check
      description: Check if the API is healthy and responding
      security: []
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "ok"

  /healthz/readiness:
    get:
      tags:
        - System
      summary: Readiness probe
      description: Check if the service and its dependencies are ready to receive traffic
      security: []
      responses:
        '200':
          description: Service ready
        '503':
          description: Service not ready

  /healthz/liveness:
    get:
      tags:
        - System
      summary: Liveness probe
      description: Simple liveness check to confirm the service is running
      security: []
      responses:
        '200':
          description: Service is alive


components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication
    SessionAuth:
      type: apiKey
      in: cookie
      name: user_session
      description: Session cookie authentication

  parameters:
    instanceID:
      name: instanceID
      in: path
      required: true
      schema:
        type: integer
      description: qBittorrent instance ID
    hash:
      name: hash
      in: path
      required: true
      schema:
        type: string
      description: Torrent hash

  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        username:
          type: string

    ApiKey:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        createdAt:
          type: string
          format: date-time
        lastUsedAt:
          type: string
          format: date-time
          nullable: true

    ClientApiKey:
      type: object
      properties:
        id:
          type: integer
        clientName:
          type: string
          description: Name of the client application
        instanceId:
          type: integer
          description: ID of the qBittorrent instance
        instanceName:
          type: string
          description: Name of the qBittorrent instance
        createdAt:
          type: string
          format: date-time
        lastUsedAt:
          type: string
          format: date-time
          nullable: true

    CrossSeedWebhookMatch:
      type: object
      properties:
        instanceId:
          type: integer
        instanceName:
          type: string
        torrentHash:
          type: string
        torrentName:
          type: string
        matchType:
          type: string
          enum: ["metadata", "exact", "size"]
          description: Type of match - metadata (no size check), exact (size < 0.1% diff), or size (within tolerance)
        sizeDiff:
          type: number
          format: double
          description: Size difference percentage (only present if size was provided)
        progress:
          type: number
          format: double
          description: Torrent completion ratio (0.0-1.0). Values below 1.0 indicate the match is still downloading.

    CrossSeedWebhookCheckResponse:
      type: object
      properties:
        canCrossSeed:
          type: boolean
          description: >-
            True only when at least one matching torrent is fully downloaded (progress 1.0).
            Pending-only matches return HTTP 202 with recommendation "download" while
            canCrossSeed remains false so clients rely on status and progress.
        matches:
          type: array
          items:
            $ref: '#/components/schemas/CrossSeedWebhookMatch'
        recommendation:
          type: string
          enum: ["download", "skip"]
          description: Recommendation - "download" if matches were found (ready or pending) or "skip" if no matches

    PathMapping:
      type: object
      description: Maps remote paths to local paths for external program execution
      properties:
        from:
          type: string
          description: Remote path prefix to match (e.g., "/mnt/remote-storage/downloads")
          example: "/mnt/remote-storage/downloads"
        to:
          type: string
          description: Local path prefix to replace with (e.g., "/home/user/downloads")
          example: "/home/user/downloads"

    ExternalProgram:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
          description: Display name for the external program
        path:
          type: string
          description: Path to the executable
        args_template:
          type: string
          description: Arguments template with variable substitution
        enabled:
          type: boolean
          description: Whether this program is enabled
        use_terminal:
          type: boolean
          description: Whether to launch in a terminal window
        path_mappings:
          type: array
          items:
            $ref: '#/components/schemas/PathMapping'
          description: Path mappings to convert remote paths to local paths for remote instances
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    Instance:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        host:
          type: string
          format: uri
        username:
          type: string
        password:
          type: string
          description: Always masked with asterisks in responses. Only used for input.
          readOnly: true
        basic_username:
          type: string
          nullable: true
        basic_password:
          type: string
          description: Always masked with asterisks in responses. Only used for input.
          readOnly: true
          nullable: true
        isActive:
          type: boolean
        last_connected_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        connected:
          type: boolean
          description: Current connection status
        connectionError:
          type: string
          description: Error message if connection failed
        hasDecryptionError:
          type: boolean
          description: Whether there's a password decryption error
        tlsSkipVerify:
          type: boolean
          description: When true, TLS certificate errors from the upstream qBittorrent instance are ignored.
        hasLocalFilesystemAccess:
          type: boolean
          description: When true, qui can access this instance's download paths locally (required for hardlink detection in automations).
        useHardlinks:
          type: boolean
          description: When true, cross-seed operations use hardlink mode for this instance.
        hardlinkBaseDir:
          type: string
          description: Base directory for hardlink trees when hardlink mode is enabled.
        hardlinkDirPreset:
          type: string
          enum: [flat, by-tracker, by-instance]
          description: Directory organization preset for hardlink mode.
        linkDirName:
          type: string
          description: Optional override for the folder name used by the by-instance hardlink/reflink preset.
        sortOrder:
          type: integer
          description: Display order preference for the instance.


    InstanceCapabilities:
      type: object
      properties:
        supportsTorrentCreation:
          type: boolean
          description: Whether the instance supports creating torrents via the Web API.
        supportsTorrentExport:
          type: boolean
          description: Whether the instance supports exporting torrent files via the Web API (requires WebAPI 2.8.11+, qBittorrent 4.5.0+).
        supportsSetTags:
          type: boolean
          description: Whether the instance supports replacing tags on torrents.
        supportsTrackerHealth:
          type: boolean
          description: Whether the instance exposes tracker health metadata (unregistered/tracker down states).
        supportsTrackerEditing:
          type: boolean
          description: Whether the instance can edit tracker URLs via the Web API (requires WebAPI 2.2.0+, qBittorrent 4.1.5+).
        supportsRenameTorrent:
          type: boolean
          description: Whether the instance supports renaming torrents (requires WebAPI 2.0.0+, qBittorrent 4.1.0+).
        supportsRenameFile:
          type: boolean
          description: Whether the instance supports renaming files within torrents (requires WebAPI 2.4.0+, qBittorrent 4.2.1+).
        supportsRenameFolder:
          type: boolean
          description: Whether the instance supports renaming folders within torrents (requires WebAPI 2.7.0+, qBittorrent 4.3.3+).
        supportsFilePriority:
          type: boolean
          description: Whether the instance supports updating torrent file priorities (requires WebAPI 2.2.0+, qBittorrent 4.1.5+).
        supportsSubcategories:
          type: boolean
          description: Whether the instance supports nested torrent categories (requires WebAPI 2.9.0+, qBittorrent 4.6.0+).
        webAPIVersion:
          type: string
          nullable: true
          description: Reported qBittorrent Web API version for the instance.


    Torrent:
      type: object
      properties:
        hash:
          type: string
        name:
          type: string
        size:
          type: integer
        progress:
          type: number
        dlSpeed:
          type: integer
        upSpeed:
          type: integer
        priority:
          type: integer
        numSeeds:
          type: integer
        numLeechs:
          type: integer
        ratio:
          type: number
        eta:
          type: integer
        state:
          type: string
        category:
          type: string
        tags:
          type: array
          items:
            type: string
        addedOn:
          type: integer
        completedOn:
          type: integer
        savePath:
          type: string

    TorrentProperties:
      type: object
      properties:
        totalDownloaded:
          type: integer
        totalUploaded:
          type: integer
        downloadSpeed:
          type: integer
        uploadSpeed:
          type: integer
        eta:
          type: integer
        seedsActual:
          type: integer
        peersActual:
          type: integer
        shareRatio:
          type: number
        uploadLimit:
          type: integer
        downloadLimit:
          type: integer
        totalSize:
          type: integer
        completedSize:
          type: integer
        additionDate:
          type: integer
        completionDate:
          type: integer
        createdBy:
          type: string
        comment:
          type: string

    Tracker:
      type: object
      properties:
        url:
          type: string
        status:
          type: integer
        tier:
          type: integer
        numPeers:
          type: integer
        numSeeds:
          type: integer
        numLeeches:
          type: integer
        msg:
          type: string

    WebSeed:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          description: HTTP source URL for the torrent

    TorrentFile:
      type: object
      properties:
        name:
          type: string
        size:
          type: integer
        progress:
          type: number
        priority:
          type: integer
        isSeed:
          type: boolean
        availability:
          type: number

    DuplicateTorrentMatch:
      type: object
      properties:
        hash:
          type: string
          description: Primary torrent hash
        infohash_v1:
          type: string
          nullable: true
          description: Legacy v1 infohash if available
        infohash_v2:
          type: string
          nullable: true
          description: v2 infohash if available
        name:
          type: string
          description: Name of the existing torrent that matched
        matched_hashes:
          type: array
          items:
            type: string
          description: Hashes from the request that matched this torrent

    Category:
      type: object
      properties:
        name:
          type: string
        savePath:
          type: string

    LogSettings:
      type: object
      description: Log configuration settings
      required:
        - level
        - path
        - maxSize
        - maxBackups
      properties:
        level:
          type: string
          description: Log level
          enum: [trace, debug, info, warn, error]
          example: "info"
        path:
          type: string
          description: Path to log file (empty for stdout only)
          example: "/var/log/qui/qui.log"
        maxSize:
          type: integer
          description: Maximum size of log file in megabytes before rotation
          example: 50
        maxBackups:
          type: integer
          description: Number of old log files to keep (0 for unlimited)
          example: 3
        configPath:
          type: string
          description: Path to the active config file being modified
          example: "/config/config.toml"
        locked:
          type: object
          description: Map of field names to lock source (environment or cli) if locked
          additionalProperties:
            type: string

    LogSettingsUpdate:
      type: object
      description: Request to update log settings
      properties:
        level:
          type: string
          description: Log level to set
          enum: [trace, debug, info, warn, error]
          example: "debug"
        path:
          type: string
          description: Path to log file
          example: "/var/log/qui/qui.log"
        maxSize:
          type: integer
          description: Maximum log file size in MB
          example: 100
        maxBackups:
          type: integer
          description: Number of backup files to keep
          example: 5

    LogExclusions:
      type: object
      description: Muted log message patterns
      required:
        - id
        - patterns
        - createdAt
        - updatedAt
      properties:
        id:
          type: integer
          description: Record ID
        patterns:
          type: array
          items:
            type: string
          description: List of log message patterns to hide
        createdAt:
          type: string
          format: date-time
          description: When the record was created
        updatedAt:
          type: string
          format: date-time
          description: When the record was last updated

    LogExclusionsInput:
      type: object
      description: Request to update log exclusions
      required:
        - patterns
      properties:
        patterns:
          type: array
          items:
            type: string
          description: List of log message patterns to hide

    LatestVersionResponse:
      type: object
      description: Information about the latest available version when an update is available
      required:
        - tag_name
        - html_url
        - published_at
      properties:
        tag_name:
          type: string
          description: The version tag (e.g., "v1.2.3")
          example: "v1.2.3"
        name:
          type: string
          nullable: true
          description: The release name/title
          example: "qui v1.2.3 - Bug fixes and improvements"
        html_url:
          type: string
          format: uri
          description: URL to the GitHub release page
          example: "https://github.com/autobrr/qui/releases/tag/v1.2.3"
        published_at:
          type: string
          format: date-time
          description: When the release was published
          example: "2025-09-23T10:30:00Z"

    QBittorrentBuildInfo:
      type: object
      description: qBittorrent build information
      properties:
        qt:
          type: string
          description: Qt framework version
          example: "5.15.2"
        libtorrent:
          type: string
          description: libtorrent library version
          example: "2.0.8"
        boost:
          type: string
          description: Boost library version
          example: "1.76.0"
        openssl:
          type: string
          description: OpenSSL library version
          example: "1.1.1k"
        zlib:
          type: string
          description: zlib library version
          example: "1.2.11"
        bitness:
          type: integer
          description: Architecture bitness (32 or 64)
          example: 64
        platform:
          type: string
          description: Operating system platform
          example: "linux"

    QBittorrentAppInfo:
      type: object
      description: qBittorrent application information
      required:
        - version
      properties:
        version:
          type: string
          description: qBittorrent version
          example: "4.6.0"
        webAPIVersion:
          type: string
          description: qBittorrent Web API version
          example: "2.11.4"
        buildInfo:
          $ref: '#/components/schemas/QBittorrentBuildInfo'

    CrossSeedInstanceResult:
      type: object
      properties:
        instance_id:
          type: integer
        instance_name:
          type: string
        success:
          type: boolean
        status:
          type: string
        message:
          type: string
          nullable: true

    CrossSeedRunResult:
      type: object
      properties:
        instanceId:
          type: integer
        instanceName:
          type: string
        indexerName:
          type: string
          nullable: true
        success:
          type: boolean
        status:
          type: string
        message:
          type: string
          nullable: true
        matchedTorrentHash:
          type: string
          nullable: true
        matchedTorrentName:
          type: string
          nullable: true

    CrossSeedRun:
      type: object
      properties:
        id:
          type: integer
        triggeredBy:
          type: string
        mode:
          type: string
          enum: [auto, manual]
        status:
          type: string
          enum: [pending, running, success, partial, failed]
        startedAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
          nullable: true
        totalFeedItems:
          type: integer
        candidatesFound:
          type: integer
        torrentsAdded:
          type: integer
        torrentsFailed:
          type: integer
        torrentsSkipped:
          type: integer
        message:
          type: string
          nullable: true
        errorMessage:
          type: string
          nullable: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/CrossSeedRunResult'

    InstanceCrossSeedCompletionSettings:
      type: object
      description: Per-instance cross-seed completion settings
      properties:
        instanceId:
          type: integer
          description: qBittorrent instance ID
        enabled:
          type: boolean
          description: Whether automatic cross-seed search is enabled for this instance
        categories:
          type: array
          items:
            type: string
          description: Only trigger for torrents in these categories (empty means all)
        tags:
          type: array
          items:
            type: string
          description: Require at least one matching tag (empty means all)
        excludeCategories:
          type: array
          items:
            type: string
          description: Skip torrents in these categories
        excludeTags:
          type: array
          items:
            type: string
          description: Skip torrents with any of these tags

    InstanceCrossSeedCompletionSettingsRequest:
      type: object
      description: Request body for updating per-instance completion settings
      properties:
        enabled:
          type: boolean
          description: Whether automatic cross-seed search is enabled for this instance
        categories:
          type: array
          items:
            type: string
          description: Only trigger for torrents in these categories (empty means all)
        tags:
          type: array
          items:
            type: string
          description: Require at least one matching tag (empty means all)
        excludeCategories:
          type: array
          items:
            type: string
          description: Skip torrents in these categories
        excludeTags:
          type: array
          items:
            type: string
          description: Skip torrents with any of these tags

    CrossSeedAutomationSettingsPatch:
      type: object
      properties:
        enabled:
          type: boolean
        runIntervalMinutes:
          type: integer
        startPaused:
          type: boolean
        category:
          type: string
          nullable: true
        tags:
          type: array
          items:
            type: string
        ignorePatterns:
          type: array
          items:
            type: string
        targetInstanceIds:
          type: array
          items:
            type: integer
        targetIndexerIds:
          type: array
          items:
            type: integer
        maxResultsPerRun:
          type: integer
          description: Deprecated; RSS automation always processes full feeds and ignores this value.
          deprecated: true
        findIndividualEpisodes:
          type: boolean
        sizeMismatchTolerancePercent:
          type: number
          format: float
        useCategoryFromIndexer:
          type: boolean
        useCrossCategorySuffix:
          type: boolean
          description: Add .cross suffix to cross-seeded torrent categories
        useCustomCategory:
          type: boolean
          description: Use a custom category for all cross-seeds
        customCategory:
          type: string
          description: Custom category name when useCustomCategory is true
        runExternalProgramId:
          type: integer
          nullable: true
        webhookSourceCategories:
          type: array
          items:
            type: string
          description: Only match against torrents in these categories when processing webhook requests (empty means all)
        webhookSourceTags:
          type: array
          items:
            type: string
          description: Only match against torrents with these tags when processing webhook requests (empty means all)
        webhookSourceExcludeCategories:
          type: array
          items:
            type: string
          description: Skip torrents in these categories when processing webhook requests
        webhookSourceExcludeTags:
          type: array
          items:
            type: string
          description: Skip torrents with any of these tags when processing webhook requests
        skipRecheck:
          type: boolean
          description: Skip cross-seed matches that would require a manual recheck
        useHardlinks:
          type: boolean
          description: Enable hardlink mode for cross-seeding (creates hardlinked file trees)
        hardlinkBaseDir:
          type: string
          description: Base directory for hardlink trees (must be on same filesystem as downloads)
        hardlinkDirPreset:
          type: string
          enum: [flat, by-tracker, by-instance]
          description: Directory organization preset for hardlink trees

    CrossSeedAutomationSettings:
      type: object
      properties:
        enabled:
          type: boolean
        runIntervalMinutes:
          type: integer
        startPaused:
          type: boolean
        category:
          type: string
          nullable: true
        tags:
          type: array
          items:
            type: string
        ignorePatterns:
          type: array
          items:
            type: string
        targetInstanceIds:
          type: array
          items:
            type: integer
        targetIndexerIds:
          type: array
          items:
            type: integer
        maxResultsPerRun:
          type: integer
          description: Deprecated; RSS automation always processes full feeds and ignores this value.
          deprecated: true
        findIndividualEpisodes:
          type: boolean
        sizeMismatchTolerancePercent:
          type: number
          format: float
        useCategoryFromIndexer:
          type: boolean
        useCrossCategorySuffix:
          type: boolean
          description: Add .cross suffix to cross-seeded torrent categories
        useCustomCategory:
          type: boolean
          description: Use a custom category for all cross-seeds
        customCategory:
          type: string
          description: Custom category name when useCustomCategory is true
        runExternalProgramId:
          type: integer
          nullable: true
        webhookSourceCategories:
          type: array
          items:
            type: string
          description: Only match against torrents in these categories when processing webhook requests (empty means all)
        webhookSourceTags:
          type: array
          items:
            type: string
          description: Only match against torrents with these tags when processing webhook requests (empty means all)
        webhookSourceExcludeCategories:
          type: array
          items:
            type: string
          description: Skip torrents in these categories when processing webhook requests
        webhookSourceExcludeTags:
          type: array
          items:
            type: string
          description: Skip torrents with any of these tags when processing webhook requests
        skipRecheck:
          type: boolean
          description: Skip cross-seed matches that would require a manual recheck
        useHardlinks:
          type: boolean
          description: Enable hardlink mode for cross-seeding (creates hardlinked file trees)
        hardlinkBaseDir:
          type: string
          description: Base directory for hardlink trees (must be on same filesystem as downloads)
        hardlinkDirPreset:
          type: string
          enum: [flat, by-tracker, by-instance]
          description: Directory organization preset for hardlink trees
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    CrossSeedAutomationStatus:
      type: object
      properties:
        settings:
          $ref: '#/components/schemas/CrossSeedAutomationSettings'
        lastRun:
          $ref: '#/components/schemas/CrossSeedRun'
          nullable: true
        nextRunAt:
          type: string
          format: date-time
          nullable: true
        running:
          type: boolean

    CrossSeedSearchSettingsPatch:
      type: object
      properties:
        instanceId:
          type: integer
          nullable: true
        categories:
          type: array
          items:
            type: string
        tags:
          type: array
          items:
            type: string
        indexerIds:
          type: array
          items:
            type: integer
        intervalSeconds:
          type: integer
        cooldownMinutes:
          type: integer

    CrossSeedSearchSettings:
      type: object
      properties:
        instanceId:
          type: integer
          nullable: true
        categories:
          type: array
          items:
            type: string
        tags:
          type: array
          items:
            type: string
        indexerIds:
          type: array
          items:
            type: integer
        intervalSeconds:
          type: integer
        cooldownMinutes:
          type: integer
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    CrossSeedRunRequest:
      type: object
      properties:
        dryRun:
          type: boolean

    CrossSeedTorrentInfo:
      type: object
      properties:
        instance_id:
          type: integer
          nullable: true
        instance_name:
          type: string
          nullable: true
        hash:
          type: string
          nullable: true
        name:
          type: string
        category:
          type: string
          nullable: true
        size:
          type: integer
          nullable: true
        progress:
          type: number
          format: float
          nullable: true
        total_files:
          type: integer
          nullable: true
        matching_files:
          type: integer
          nullable: true
        file_count:
          type: integer
          nullable: true
        content_type:
          type: string
          nullable: true
        search_type:
          type: string
          nullable: true
        search_categories:
          type: array
          items:
            type: integer
        required_caps:
          type: array
          items:
            type: string
        available_indexers:
          type: array
          items:
            type: integer
        filtered_indexers:
          type: array
          items:
            type: integer
        excluded_indexers:
          type: object
          additionalProperties:
            type: string
        content_matches:
          type: array
          items:
            type: string
        content_filtering_completed:
          type: boolean
          nullable: true

    AsyncIndexerFilteringState:
      type: object
      properties:
        capabilities_completed:
          type: boolean
        content_completed:
          type: boolean
        capability_indexers:
          type: array
          items:
            type: integer
        filtered_indexers:
          type: array
          items:
            type: integer
        excluded_indexers:
          type: object
          additionalProperties:
            type: string
        content_matches:
          type: array
          items:
            type: string
        error:
          type: string

    CrossSeedTorrentSearchRequest:
      type: object
      properties:
        query:
          type: string
        limit:
          type: integer
          minimum: 1
        indexer_ids:
          type: array
          items:
            type: integer

    CrossSeedTorrentSearchResult:
      type: object
      properties:
        indexer:
          type: string
        indexer_id:
          type: integer
        title:
          type: string
        download_url:
          type: string
        info_url:
          type: string
          nullable: true
        size:
          type: integer
        seeders:
          type: integer
        leechers:
          type: integer
        category_id:
          type: integer
        category_name:
          type: string
        publish_date:
          type: string
          format: date-time
        download_volume_factor:
          type: number
        upload_volume_factor:
          type: number
        guid:
          type: string
        imdb_id:
          type: string
          nullable: true
        tvdb_id:
          type: string
          nullable: true
        match_reason:
          type: string
          nullable: true
        match_score:
          type: number

    CrossSeedResponse:
      type: object
      properties:
        success:
          type: boolean
        results:
          type: array
          items:
            $ref: '#/components/schemas/CrossSeedInstanceResult'
        torrentInfo:
          $ref: '#/components/schemas/CrossSeedTorrentInfo'
          nullable: true

    CrossSeedTorrentSearchResponse:
      type: object
      properties:
        source_torrent:
          $ref: '#/components/schemas/CrossSeedTorrentInfo'
        results:
          type: array
          items:
            $ref: '#/components/schemas/CrossSeedTorrentSearchResult'

    CrossSeedApplySelection:
      type: object
      required:
        - indexer_id
        - indexer
        - download_url
        - title
      properties:
        indexer_id:
          type: integer
        indexer:
          type: string
        download_url:
          type: string
        title:
          type: string
        guid:
          type: string
          nullable: true

    CrossSeedApplyRequest:
      type: object
      required:
        - selections
        - use_tag
      properties:
        selections:
          type: array
          items:
            $ref: '#/components/schemas/CrossSeedApplySelection'
        use_tag:
          type: boolean
        tag_name:
          type: string
          nullable: true
        start_paused:
          type: boolean
          nullable: true

    CrossSeedApplyResult:
      type: object
      properties:
        title:
          type: string
        indexer:
          type: string
        torrent_name:
          type: string
          nullable: true
        success:
          type: boolean
        instance_results:
          type: array
          items:
            $ref: '#/components/schemas/CrossSeedInstanceResult'
        error:
          type: string
          nullable: true

    CrossSeedApplyResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/CrossSeedApplyResult'

    CrossInstanceFilterOptions:
      type: object
      description: Filter options for cross-instance torrent filtering
      required:
        - expr
      properties:
        expr:
          type: string
          description: Expression filter (required for cross-instance filtering). Supports logical operators and hash matching.
          example: 'Hash == "abcd1234" || Hash == "efgh5678"'
        status:
          type: array
          items:
            type: string
          description: Filter by torrent status
        excludeStatus:
          type: array
          items:
            type: string
          description: Array of strings to omit torrents with these statuses
        categories:
          type: array
          items:
            type: string
          description: Filter by categories
        excludeCategories:
          type: array
          items:
            type: string
          description: Array of strings to omit specified categories
        tags:
          type: array
          items:
            type: string
          description: Filter by tags
        excludeTags:
          type: array
          items:
            type: string
          description: Exclude torrents with these tags
        trackers:
          type: array
          items:
            type: string
          description: Filter by tracker hostnames
        excludeTrackers:
          type: array
          items:
            type: string
          description: Array of tracker hostnames to exclude
        hashes:
          type: array
          items:
            type: string
          description: Array of torrent hashes to explicitly include

    BackupRun:
      type: object
      properties:
        id:
          type: integer
          format: int64
        instanceId:
          type: integer
        kind:
          type: string
          enum: ["manual", "hourly", "daily", "weekly", "monthly"]
        status:
          type: string
          enum: ["pending", "running", "success", "failed", "canceled"]
        requestedBy:
          type: string
        requestedAt:
          type: string
          format: date-time
        startedAt:
          type: string
          format: date-time
          nullable: true
        completedAt:
          type: string
          format: date-time
          nullable: true
        archivePath:
          type: string
          nullable: true
        manifestPath:
          type: string
          nullable: true
        totalBytes:
          type: integer
          format: int64
        torrentCount:
          type: integer
        categoryCounts:
          type: object
          additionalProperties:
            type: integer
          nullable: true
        errorMessage:
          type: string
          nullable: true
        categories:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/CategorySnapshot'
          nullable: true
        tags:
          type: array
          items:
            type: string
          nullable: true

    CategorySnapshot:
      type: object
      properties:
        savePath:
          type: string

    OrphanScanSettings:
      type: object
      properties:
        id:
          type: integer
          format: int64
        instanceId:
          type: integer
        enabled:
          type: boolean
          description: Whether scheduled orphan scanning is enabled
        gracePeriodMinutes:
          type: integer
          description: Skip files modified within this many minutes
        ignorePaths:
          type: array
          items:
            type: string
          description: Absolute paths to exclude from scanning
        scanIntervalHours:
          type: integer
          description: Hours between scheduled scans
        maxFilesPerRun:
          type: integer
          description: Maximum orphan files to record per run (prevents DB bloat)
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    OrphanScanSettingsUpdate:
      type: object
      properties:
        enabled:
          type: boolean
        gracePeriodMinutes:
          type: integer
          minimum: 0
        ignorePaths:
          type: array
          items:
            type: string
        scanIntervalHours:
          type: integer
          minimum: 1
        maxFilesPerRun:
          type: integer
          minimum: 1

    OrphanScanRun:
      type: object
      properties:
        id:
          type: integer
          format: int64
        instanceId:
          type: integer
        status:
          type: string
          enum: ["pending", "scanning", "preview_ready", "deleting", "completed", "failed", "canceled"]
        triggeredBy:
          type: string
          enum: ["manual", "scheduled"]
        scanPaths:
          type: array
          items:
            type: string
          description: Directories that were scanned (derived from torrent SavePath values)
        filesFound:
          type: integer
          description: Number of orphan files found
        filesDeleted:
          type: integer
          description: Number of files deleted (after confirmation)
        foldersDeleted:
          type: integer
          description: Number of empty folders deleted
        bytesReclaimed:
          type: integer
          format: int64
          description: Total bytes freed
        truncated:
          type: boolean
          description: True if max_files_per_run was reached and more orphans may exist
        errorMessage:
          type: string
          nullable: true
        startedAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
          nullable: true

    OrphanScanFile:
      type: object
      properties:
        id:
          type: integer
          format: int64
        runId:
          type: integer
          format: int64
        filePath:
          type: string
          description: Absolute path to the orphan file
        fileSize:
          type: integer
          format: int64
          description: File size in bytes
        modifiedAt:
          type: string
          format: date-time
          nullable: true
        status:
          type: string
          enum: ["pending", "deleted", "skipped", "failed"]
        errorMessage:
          type: string
          nullable: true

    OrphanScanRunWithFiles:
      allOf:
        - $ref: '#/components/schemas/OrphanScanRun'
        - type: object
          properties:
            files:
              type: array
              items:
                $ref: '#/components/schemas/OrphanScanFile'

    ArrInstance:
      type: object
      properties:
        id:
          type: integer
        type:
          type: string
          enum: ["sonarr", "radarr"]
        name:
          type: string
        base_url:
          type: string
        basic_username:
          type: string
          nullable: true
        enabled:
          type: boolean
        priority:
          type: integer
        timeout_seconds:
          type: integer
        last_test_at:
          type: string
          format: date-time
          nullable: true
        last_test_status:
          type: string
          enum: ["unknown", "ok", "error"]
        last_test_error:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    ArrInstanceCreate:
      type: object
      required:
        - type
        - name
        - base_url
        - api_key
      properties:
        type:
          type: string
          enum: ["sonarr", "radarr"]
        name:
          type: string
        base_url:
          type: string
        api_key:
          type: string
          writeOnly: true
        basic_username:
          type: string
          description: Optional HTTP basic auth username for reverse proxies
        basic_password:
          type: string
          writeOnly: true
          description: Optional HTTP basic auth password for reverse proxies
        enabled:
          type: boolean
          default: true
        priority:
          type: integer
          default: 0
        timeout_seconds:
          type: integer
          default: 15

    ArrInstanceUpdate:
      type: object
      properties:
        name:
          type: string
        base_url:
          type: string
        api_key:
          type: string
          writeOnly: true
          description: Only update if provided
        basic_username:
          type: string
          description: Optional HTTP basic auth username for reverse proxies (empty string clears)
        basic_password:
          type: string
          writeOnly: true
          description: Optional HTTP basic auth password for reverse proxies
        enabled:
          type: boolean
        priority:
          type: integer
        timeout_seconds:
          type: integer

    ArrTestConnectionRequest:
      type: object
      required:
        - type
        - base_url
        - api_key
      properties:
        type:
          type: string
          enum: ["sonarr", "radarr"]
        base_url:
          type: string
        api_key:
          type: string
          writeOnly: true
        basic_username:
          type: string
          description: Optional HTTP basic auth username for reverse proxies
        basic_password:
          type: string
          writeOnly: true
          description: Optional HTTP basic auth password for reverse proxies

    ArrTestResponse:
      type: object
      properties:
        success:
          type: boolean
        error:
          type: string
          nullable: true

    ArrResolveRequest:
      type: object
      required:
        - title
        - content_type
      properties:
        title:
          type: string
        content_type:
          type: string
          enum: ["movie", "tv"]

    ArrExternalIDs:
      type: object
      properties:
        imdb_id:
          type: string
        tmdb_id:
          type: integer
        tvdb_id:
          type: integer
        tvmaze_id:
          type: integer

    ArrIDCacheEntry:
      type: object
      properties:
        id:
          type: integer
          format: int64
        title_hash:
          type: string
        content_type:
          type: string
        arr_instance_id:
          type: integer
          nullable: true
        external_ids:
          $ref: '#/components/schemas/ArrExternalIDs'
        is_negative:
          type: boolean
        cached_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time

    ArrInstanceResult:
      type: object
      properties:
        instance_id:
          type: integer
        instance_name:
          type: string
        instance_type:
          type: string
        ids:
          $ref: '#/components/schemas/ArrExternalIDs'
        error:
          type: string
          nullable: true

    ArrResolveResponse:
      type: object
      properties:
        title:
          type: string
        title_hash:
          type: string
        content_type:
          type: string
          enum: ["movie", "tv"]
        cache_hit:
          type: boolean
        cache_entry:
          $ref: '#/components/schemas/ArrIDCacheEntry'
        instances_available:
          type: integer
        instance_results:
          type: array
          items:
            $ref: '#/components/schemas/ArrInstanceResult'
        error:
          type: string
          nullable: true

tags:
  - name: Authentication
    description: User authentication and session management
  - name: API Keys
    description: API key management
  - name: ARR Integrations
    description: Sonarr/Radarr instance management for external ID lookups
  - name: Client API Keys
    description: Client API key management for external applications
  - name: External Programs
    description: Manage and execute external applications
  - name: Instances
    description: qBittorrent instance management
  - name: Torrents
    description: Torrent operations
  - name: Torrent Details
    description: Individual torrent information
  - name: Categories
    description: Category management
  - name: Tags
    description: Tag management
  - name: Cross-Seed
    description: Cross-seeding operations for finding and adding duplicate torrents
  - name: Orphan Scan
    description: Orphan file scanning and cleanup (files on disk not associated with any torrent)
  - name: Theme Licenses
    description: Theme license management (optional feature)
  - name: Proxy
    description: qBittorrent-compatible proxy endpoints authenticated by client API key