autobrr Backups API

openapi: 3.2.0
info:
  title: qui Backups 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: Backups
paths:
  /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
      operationId: postApiInstancesByInstanceIDBackupsImport
      x-operation-id-source: derived
  /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
      operationId: postApiInstancesByInstanceIDBackupsRunsByRunIdRestorePreview
      x-operation-id-source: derived
  /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
      operationId: postApiInstancesByInstanceIDBackupsRunsByRunIdRestore
      x-operation-id-source: derived
  /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
      operationId: getApiInstancesByInstanceIDBackupsRunsByRunIdDownload
      x-operation-id-source: derived
  /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
      operationId: getApiInstancesByInstanceIDBackupsRunsByRunIdItemsByTorrentHashDownload
      x-operation-id-source: derived
components:
  schemas:
    CategorySnapshot:
      type: object
      properties:
        savePath:
          type: string
    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
  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.

        '