autobrr System API

openapi: 3.2.0
info:
  title: qui System 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: System
paths:
  /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'
      operationId: getApiLogSettings
      x-operation-id-source: derived
    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
      operationId: putApiLogSettings
      x-operation-id-source: derived
  /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'
      operationId: getApiLogExclusions
      x-operation-id-source: derived
    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'
      operationId: putApiLogExclusions
      x-operation-id-source: derived
  /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
      operationId: getApiLogsStream
      x-operation-id-source: derived
  /api/logs/files:
    get:
      tags:
      - System
      summary: List log files
      description: List the log files (active and rotated) in the configured log directory. Returns an empty list when file logging is not configured.
      responses:
        '200':
          description: Log files available for download
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LogFile'
      operationId: getApiLogsFiles
      x-operation-id-source: derived
  /api/logs/files/{filename}:
    get:
      tags:
      - System
      summary: Download a log file
      description: Download a single log file from the configured log directory. The filename must exactly match an entry returned by the log file listing.
      parameters:
      - name: filename
        in: path
        required: true
        description: Log file name as returned by the listing endpoint
        schema:
          type: string
      responses:
        '200':
          description: Log file content
          content:
            text/plain:
              schema:
                type: string
                format: binary
        '404':
          description: Log file not found
      operationId: getApiLogsFilesByFilename
      x-operation-id-source: derived
  /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
      operationId: getApiVersionLatest
      x-operation-id-source: derived
  /api/version:
    get:
      tags:
      - System
      summary: Get current running version
      description: Returns the version qui is currently running, along with whether a newer release is available. Useful for monitoring tools (e.g. Argus) that track the deployed version of a service.
      responses:
        '200':
          description: Current version information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionResponse'
      operationId: getApiVersion
      x-operation-id-source: derived
  /api/system/restart:
    post:
      tags:
      - System
      summary: Restart qui
      description: Runs the same graceful shutdown as SIGTERM, then restarts qui in place with the same process ID and command line. qui checks the binary before the shutdown. Only one update or restart runs at a time.
      responses:
        '202':
          description: The restart started
        '403':
          description: Restart is not available, for example in an app container
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: An update or restart is already running
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: The binary is missing, is not a regular file, or is not executable. qui keeps running.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: postApiSystemRestart
      x-operation-id-source: derived
  /api/system/update:
    post:
      tags:
      - System
      summary: Install a release
      description: Downloads the release with this exact tag, checks its signature, and replaces the binary. qui keeps the previous binary as qui-v.bak next to it and deletes older backups. After the 200 response qui restarts. On an install error the binary and the process do not change. When qui refuses the restart after the install, it returns 500, the new binary stays in place, and the old process keeps running. Only one update or restart runs at a time.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SelfUpdateRequest'
      responses:
        '200':
          description: The new binary is in place. qui restarts next.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SelfUpdateResponse'
        '400':
          description: The version is missing or is not valid semver
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Self-update is not available, for example in an app container or for a development build
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: GitHub has no release with that tag, or no asset for this OS and architecture
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The tag is not newer than the running version, or an update or restart is already running
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: The binary swap failed, for example with a permission error, or the new binary is installed but qui refused the restart
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: GitHub returned an error, such as a rate limit, or the signature check failed. The error carries the message word for word.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: postApiSystemUpdate
      x-operation-id-source: derived
  /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
      operationId: getHealth
      x-operation-id-source: derived
  /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
      operationId: getHealthzReadiness
      x-operation-id-source: derived
  /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
      operationId: getHealthzLiveness
      x-operation-id-source: derived
components:
  schemas:
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string
    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
    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
    SelfUpdateResponse:
      type: object
      required:
      - version
      - rollbackCommand
      - backupError
      properties:
        version:
          type: string
          description: The installed version, without a v prefix, in the same format as GET /api/version
          example: 1.31.0
        rollbackCommand:
          type: string
          description: The command that restores the backup, one line for each replaced binary. Empty when qui found no backup.
          example: mv '/home/user/bin/qui-v1.30.0.bak' '/home/user/bin/qui'
        backupError:
          type: string
          description: Empty when the backup exists. Otherwise it names the path that qui checked and the cause.
          example: ''
    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
    LogFile:
      type: object
      description: A log file available for download
      required:
      - name
      - sizeBytes
      - modTime
      properties:
        name:
          type: string
          description: Log file name
          example: qui.log
        sizeBytes:
          type: integer
          format: int64
          description: File size in bytes
          example: 1048576
        modTime:
          type: string
          format: date-time
          description: Last modification time
    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
    SelfUpdateRequest:
      type: object
      required:
      - version
      properties:
        version:
          type: string
          description: The release tag to install
          example: v1.31.0
    VersionResponse:
      type: object
      description: The version qui is currently running and whether a newer release is available
      required:
      - version
      - updateAvailable
      - selfUpdate
      - selfUpdateUnavailableReason
      - restart
      properties:
        version:
          type: string
          description: The version qui is currently running
          example: v1.2.3
        latestVersion:
          type: string
          description: The latest available release tag. Present only when a newer release than the running version has been detected.
          example: v1.3.0
        updateAvailable:
          type: boolean
          description: Whether a newer release than the running version is available
          example: true
        selfUpdate:
          type: boolean
          description: Whether qui can replace its own binary with a release. False in an app container, for a build that is not a release, when the directory of the binary is not writable, or when `disableSelfUpdate` is set.
          example: true
        selfUpdateUnavailableReason:
          type: string
          enum:
          - ''
          - container
          - disabled
          - development
          - directory
          description: The first blocker for Self-update, in container, configuration, release build, and binary directory order. Empty when Self-update is available.
          example: container
        restart:
          type: boolean
          description: Whether qui can restart itself. False in an app container.
          example: true
    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'
  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.

        '