autobrr Orphan Scan API

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

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

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

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

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


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

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

    Set `conditions.category.enabled` to `false` to disable the category action.'
  version: 1.0.0
  license:
    name: GPL-2.0-or-later
    url: https://opensource.org/licenses/GPL-2.0
servers:
- url: http://localhost:7476
  description: Local development server
- url: /
  description: Current server
security:
- ApiKeyAuth: []
- SessionAuth: []
tags:
- name: Orphan Scan
  description: Orphan file scanning and cleanup (files on disk not associated with any torrent)
paths:
  /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
      operationId: getApiInstancesByInstanceIDOrphanScanSettings
      x-operation-id-source: derived
    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
      operationId: putApiInstancesByInstanceIDOrphanScanSettings
      x-operation-id-source: derived
  /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. A preview_ready run from a scan of a remote instance that did not read every file's identity (`identityComplete` false) cannot be confirmed, so the new scan cancels it instead of returning 409.
      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
      operationId: postApiInstancesByInstanceIDOrphanScanScan
      x-operation-id-source: derived
  /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
      operationId: getApiInstancesByInstanceIDOrphanScanRuns
      x-operation-id-source: derived
  /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
      operationId: getApiInstancesByInstanceIDOrphanScanRunsByRunID
      x-operation-id-source: derived
    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
      operationId: deleteApiInstancesByInstanceIDOrphanScanRunsByRunID
      x-operation-id-source: derived
  /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. Also returned when the run scanned a remote instance that does not report file identity, or whose scan did not read it for every file, where the run stays preview_ready. And when the instance's filesystem access or SSH endpoint changed since the scan, which marks the run failed.
        '403':
          description: Instance does not have local filesystem access enabled
        '404':
          description: Run not found
      operationId: postApiInstancesByInstanceIDOrphanScanRunsByRunIDConfirm
      x-operation-id-source: derived
components:
  schemas:
    OrphanScanFile:
      type: object
      properties:
        id:
          type: integer
          format: int64
        runId:
          type: integer
          format: int64
        filePath:
          type: string
          description: Absolute path to the entry. Usually a file, but a disc unit (BDMV/VIDEO_TS) is reported as a single entry whose path is its directory, and an abandoned directory is a directory too.
        fileSize:
          type: integer
          format: int64
          description: Entry size in bytes; always 0 for an abandoned directory
        isAbandonedDir:
          type: boolean
          description: 'True only for an abandoned directory: one the run empties, either already holding no files or holding only orphans listed in the same run, and removed with rmdir after them. False for orphan content, whose path may still be a directory when it is a disc unit.'
        modifiedAt:
          type: string
          format: date-time
          nullable: true
        status:
          type: string
          enum:
          - pending
          - deleted
          - skipped
          - failed
        errorMessage:
          type: string
          nullable: true
    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
        previewSort:
          type: string
          description: Sorting applied to the orphan preview list
          enum:
          - size_desc
          - directory_size_desc
        maxFilesPerRun:
          type: integer
          description: Maximum orphan entries, files and directories together, to record per run (prevents DB bloat)
        scanDefaultSavePath:
          type: boolean
          description: Also scan qBittorrent's default save path, even when no torrent points into it
        scanCategoryPaths:
          type: boolean
          description: Also scan every qBittorrent category destination; false when scanDefaultSavePath is false
        deleteAbandonedDirs:
          type: boolean
          description: Report directories the run empties, so they can be removed with the orphan files
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    OrphanScanRunWithFiles:
      allOf:
      - $ref: '#/components/schemas/OrphanScanRun'
      - type: object
        properties:
          files:
            type: array
            items:
              $ref: '#/components/schemas/OrphanScanFile'
    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 selected for scanning. Some paths can be unavailable during a partial scan.
        filesFound:
          type: integer
          description: Number of orphan entries found, files and abandoned directories together
        filesDeleted:
          type: integer
          description: Number of files deleted (after confirmation)
        foldersDeleted:
          type: integer
          description: Number of abandoned directories 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
        partial:
          type: boolean
          description: True when some selected scan paths could not be scanned. Automatic cleanup is skipped for this run.
        filesystemMode:
          type: string
          enum:
          - none
          - local
          - remote
          description: How qui reached the instance's files when this run scanned them. Deletion is refused for runs whose mode no longer matches the instance, and for `remote` runs without `identityComplete` or whose SSH endpoint changed since the scan.
        identityComplete:
          type: boolean
          description: True when the scan read a file identity for every regular file it listed or protected. A `remote` run can be deleted only when it is true, since without identity a second path to a torrent's file looks like an orphan.
        errorMessage:
          type: string
          nullable: true
        startedAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
          nullable: true
    OrphanScanSettingsUpdate:
      type: object
      properties:
        enabled:
          type: boolean
        gracePeriodMinutes:
          type: integer
          minimum: 0
        ignorePaths:
          type: array
          items:
            type: string
        scanIntervalHours:
          type: integer
          minimum: 1
        previewSort:
          type: string
          enum:
          - size_desc
          - directory_size_desc
        maxFilesPerRun:
          type: integer
          minimum: 1
        scanDefaultSavePath:
          type: boolean
        scanCategoryPaths:
          type: boolean
          description: Cleared when scanDefaultSavePath is false
        deleteAbandonedDirs:
          type: boolean
  parameters:
    instanceID:
      name: instanceID
      in: path
      required: true
      schema:
        type: integer
        minimum: 0
      description: qBittorrent instance ID. 0 is the unified scope on the endpoints that support it.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication
    ApiKeyQuery:
      type: apiKey
      in: query
      name: apikey
      description: API key via query parameter for external webhook integrations
    SessionAuth:
      type: apiKey
      in: cookie
      name: qui_user_session
      description: 'Browser session cookie set by the qui web UI. POST, PUT, PATCH, and DELETE

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

        header. Other clients should use an API key.

        '