autobrr Torrent Details API

openapi: 3.2.0
info:
  title: qui Torrent Details 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: Torrent Details
  description: Individual torrent information
paths:
  /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
      operationId: getApiInstancesByInstanceIDTorrentsByHashExport
      x-operation-id-source: derived
  /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'
      operationId: getApiInstancesByInstanceIDTorrentsByHashProperties
      x-operation-id-source: derived
  /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'
      operationId: getApiInstancesByInstanceIDTorrentsByHashTrackers
      x-operation-id-source: derived
    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
      operationId: putApiInstancesByInstanceIDTorrentsByHashTrackers
      x-operation-id-source: derived
    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
      operationId: postApiInstancesByInstanceIDTorrentsByHashTrackers
      x-operation-id-source: derived
    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
      operationId: deleteApiInstancesByInstanceIDTorrentsByHashTrackers
      x-operation-id-source: derived
  /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
      operationId: getApiInstancesByInstanceIDTorrentsByHashWebseeds
      x-operation-id-source: derived
  /api/instances/{instanceID}/torrents/{hash}/pieces:
    get:
      tags:
      - Torrent Details
      summary: Get torrent piece states
      description: 'Get download state of each piece for a torrent.

        States: 0 = not downloaded, 1 = downloading, 2 = downloaded'
      parameters:
      - $ref: '#/components/parameters/instanceID'
      - $ref: '#/components/parameters/hash'
      responses:
        '200':
          description: Array of piece states
          content:
            application/json:
              schema:
                type: array
                items:
                  type: integer
                  minimum: 0
                  maximum: 2
                  description: 'Piece state: 0 = not downloaded, 1 = downloading, 2 = downloaded'
        '400':
          description: Invalid request
        '500':
          description: Failed to get piece states
      operationId: getApiInstancesByInstanceIDTorrentsByHashPieces
      x-operation-id-source: derived
  /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'
      operationId: getApiInstancesByInstanceIDTorrentsByHashFiles
      x-operation-id-source: derived
    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
      operationId: putApiInstancesByInstanceIDTorrentsByHashFiles
      x-operation-id-source: derived
  /api/instances/{instanceID}/torrents/{hash}/files/{fileIndex}/download:
    get:
      tags:
      - Torrent Details
      summary: Download a torrent content file
      description: Streams a single file from the torrent's content on the local filesystem. Requires the instance to have local filesystem access enabled.
      parameters:
      - $ref: '#/components/parameters/instanceID'
      - $ref: '#/components/parameters/hash'
      - $ref: '#/components/parameters/fileIndex'
      responses:
        '200':
          description: Binary file stream
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          description: Invalid instance ID, hash, or file index
        '403':
          description: Instance does not have local filesystem access
        '404':
          description: Torrent, file index, or file on disk not found
        '500':
          description: Internal server error
      operationId: getApiInstancesByInstanceIDTorrentsByHashFilesByFileIndexDownload
      x-operation-id-source: derived
  /api/instances/{instanceID}/torrents/{hash}/files/{fileIndex}/mediainfo:
    get:
      tags:
      - Torrent Details
      summary: Get MediaInfo for a torrent content file
      description: Analyzes a single file from the torrent's content on the local filesystem and returns a human-readable stream/field report plus the raw MediaInfo JSON output. Requires the instance to have local filesystem access enabled.
      parameters:
      - $ref: '#/components/parameters/instanceID'
      - $ref: '#/components/parameters/hash'
      - $ref: '#/components/parameters/fileIndex'
      responses:
        '200':
          description: MediaInfo report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TorrentFileMediaInfoResponse'
        '400':
          description: Invalid instance ID, hash, or file index
        '403':
          description: Instance does not have local filesystem access
        '404':
          description: Torrent, file index, or file on disk not found
        '500':
          description: Internal server error
      operationId: getApiInstancesByInstanceIDTorrentsByHashFilesByFileIndexMediainfo
      x-operation-id-source: derived
  /api/instances/{instanceID}/mediainfo:
    get:
      tags:
      - Torrent Details
      summary: Get MediaInfo for an instance content path
      description: Analyzes a file from an instance-relative content path and returns both text summary and parsed MediaInfo JSON output. Requires the instance to have local filesystem access enabled.
      parameters:
      - $ref: '#/components/parameters/instanceID'
      - name: contentPath
        in: query
        required: true
        description: 'Canonical instance-relative content path parameter (legacy alias: content_path)'
        schema:
          type: string
      - name: content_path
        in: query
        deprecated: true
        required: false
        description: Legacy alias for contentPath (maps to the canonical contentPath parameter)
        schema:
          type: string
      responses:
        '200':
          description: MediaInfo summary and JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentPathMediaInfoResponse'
        '400':
          description: Invalid instance ID or content path
        '403':
          description: Instance does not have local filesystem access
        '404':
          description: File not found on disk
        '500':
          description: Internal server error
      operationId: getApiInstancesByInstanceIDMediainfo
      x-operation-id-source: derived
  /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
      operationId: putApiInstancesByInstanceIDTorrentsByHashRename
      x-operation-id-source: derived
  /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
      operationId: putApiInstancesByInstanceIDTorrentsByHashRenameFile
      x-operation-id-source: derived
  /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
      operationId: putApiInstancesByInstanceIDTorrentsByHashRenameFolder
      x-operation-id-source: derived
  /api/instances/{instanceID}/torrents/{hash}/peers:
    get:
      tags:
      - Torrent Details
      summary: Get torrent peers
      description: Get the current merged peer list for a torrent. The response omits full_update.
      parameters:
      - $ref: '#/components/parameters/instanceID'
      - $ref: '#/components/parameters/hash'
      responses:
        '200':
          description: Current peers and sorted peer list
          content:
            application/json:
              schema:
                type: object
                required:
                - rid
                properties:
                  peers:
                    type: object
                    description: Peers keyed by canonical peer address.
                    additionalProperties:
                      $ref: '#/components/schemas/TorrentPeer'
                  peers_removed:
                    type: array
                    items:
                      type: string
                  rid:
                    type: integer
                    format: int64
                  show_flags:
                    type: boolean
                  sorted_peers:
                    type: array
                    description: Seeders first, then descending progress, download speed and upload speed. Canonical peer address breaks ties.
                    items:
                      allOf:
                      - $ref: '#/components/schemas/TorrentPeer'
                      - type: object
                        required:
                        - key
                        properties:
                          key:
                            type: string
                            description: Canonical peer address.
      operationId: getApiInstancesByInstanceIDTorrentsByHashPeers
      x-operation-id-source: derived
components:
  schemas:
    WebSeed:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          description: HTTP source URL for the torrent
    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
    TorrentFileMediaInfoStream:
      type: object
      required:
      - kind
      - fields
      properties:
        kind:
          type: string
          description: Stream kind (General, Video, Audio, Text, etc.)
        fields:
          type: array
          items:
            $ref: '#/components/schemas/TorrentFileMediaInfoField'
    TorrentPeer:
      type: object
      required:
      - progress
      properties:
        ip:
          type: string
        port:
          type: integer
        connection:
          type: string
        flags:
          type: string
        flags_desc:
          type: string
        client:
          type: string
        progress:
          type: number
        dl_speed:
          type: integer
          format: int64
        up_speed:
          type: integer
          format: int64
        downloaded:
          type: integer
          format: int64
        uploaded:
          type: integer
          format: int64
        relevance:
          type: number
        files:
          type: string
        country:
          type: string
        country_code:
          type: string
        peer_id_client:
          type: string
    TorrentFileMediaInfoField:
      type: object
      required:
      - name
      - value
      properties:
        name:
          type: string
        value:
          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
    TorrentFileMediaInfoResponse:
      type: object
      required:
      - fileIndex
      - relativePath
      - streams
      - rawJSON
      properties:
        fileIndex:
          type: integer
        relativePath:
          type: string
          description: Torrent-relative path from qBittorrent file list
        streams:
          type: array
          items:
            $ref: '#/components/schemas/TorrentFileMediaInfoStream'
        rawJSON:
          type: string
          description: Raw MediaInfo JSON output
    TorrentFile:
      type: object
      properties:
        name:
          type: string
        size:
          type: integer
        progress:
          type: number
        priority:
          type: integer
        isSeed:
          type: boolean
        availability:
          type: number
    ContentPathMediaInfoResponse:
      type: object
      required:
      - contentPath
      - summaryTxt
      - mediaInfoJson
      properties:
        contentPath:
          type: string
          description: Normalized instance-relative file path that was analyzed
        summaryTxt:
          type: string
          description: Human-readable MediaInfo text summary
        mediaInfoJson:
          type: object
          description: Parsed MediaInfo JSON output
          additionalProperties: true
  parameters:
    hash:
      name: hash
      in: path
      required: true
      schema:
        type: string
      description: Torrent hash
    fileIndex:
      name: fileIndex
      in: path
      required: true
      schema:
        type: integer
        minimum: 0
      description: Torrent file index
    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.

        '