qbittorrent_web_api/qbittorrent-web-api-gen/api-4_1.md

This WebUI API documentation applies to qBittorrent v4.1+. For other WebUI API versions, visit [WebUI API](https://github.com/qbittorrent/qBittorrent/wiki#WebUI-API).

# Table of Contents #

1. [Changes](#changes)
   1. [API v2.0](#api-v20)
   1. [API v2.0.1](#api-v201)
   1. [API v2.0.2](#api-v202)
   1. [API v2.1.0](#api-v210)
   1. [API v2.1.1](#api-v211)
   1. [API v2.2.0](#api-v220)
   1. [API v2.2.1](#api-v221)
   1. [API v2.3.0](#api-v230)
   1. [API v2.4.0](#api-v240)
   1. [API v2.4.1](#api-v241)
   1. [API v2.5.0](#api-v250)
   1. [API v2.5.1](#api-v251)
   1. [API v2.6.0](#api-v260)
   1. [API v2.6.1](#api-v261)
   1. [API v2.6.2](#api-v262)
   1. [API v2.7.0](#api-v270)
   1. [API v2.8.0](#api-v280)
   1. [API v2.8.1](#api-v281)
   1. [API v2.8.2](#api-v282)
   1. [API v2.8.3](#api-v283)
1. [General information](#general-information)
1. [Authentication](#authentication)
   1. [Login](#login)
   1. [Logout](#logout)
1. [Application](#application)
   1. [Get application version](#get-application-version)
   1. [Get API version](#get-api-version)
   1. [Get build info](#get-build-info)
   1. [Shutdown application](#shutdown-application)
   1. [Get application preferences](#get-application-preferences)
   1. [Set application preferences](#set-application-preferences)
   1. [Get default save path](#get-default-save-path)
1. [Log](#log)
   1. [Get log](#get-log)
   1. [Get peer log](#get-peer-log)
1. [Sync](#sync)
   1. [Get main data](#get-main-data)
   1. [Get torrent peers data](#get-torrent-peers-data)
1. [Transfer info](#transfer-info)
   1. [Get global transfer info](#get-global-transfer-info)
   1. [Get alternative speed limits state](#get-alternative-speed-limits-state)
   1. [Toggle alternative speed limits](#toggle-alternative-speed-limits)
   1. [Get global download limit](#get-global-download-limit)
   1. [Set global download limit](#set-global-download-limit)
   1. [Get global upload limit](#get-global-upload-limit)
   1. [Set global upload limit](#set-global-upload-limit)
   1. [Ban peers](#ban-peers)
1. [Torrent management](#torrent-management)
   1. [Get torrent list](#get-torrent-list)
   1. [Get torrent generic properties](#get-torrent-generic-properties)
   1. [Get torrent trackers](#get-torrent-trackers)
   1. [Get torrent web seeds](#get-torrent-web-seeds)
   1. [Get torrent contents](#get-torrent-contents)
   1. [Get torrent pieces' states](#get-torrent-pieces-states)
   1. [Get torrent pieces' hashes](#get-torrent-pieces-hashes)
   1. [Pause torrents](#pause-torrents)
   1. [Resume torrents](#resume-torrents)
   1. [Delete torrents](#delete-torrents)
   1. [Recheck torrents](#recheck-torrents)
   1. [Reannounce torrents](#reannounce-torrents)
   1. [Edit trackers](#edit-trackers)
   1. [Remove trackers](#remove-trackers)
   1. [Add peers](#add-peers)
   1. [Add new torrent](#add-new-torrent)
   1. [Add trackers to torrent](#add-trackers-to-torrent)
   1. [Increase torrent priority](#increase-torrent-priority)
   1. [Decrease torrent priority](#decrease-torrent-priority)
   1. [Maximal torrent priority](#maximal-torrent-priority)
   1. [Minimal torrent priority](#minimal-torrent-priority)
   1. [Set file priority](#set-file-priority)
   1. [Get torrent download limit](#get-torrent-download-limit)
   1. [Set torrent download limit](#set-torrent-download-limit)
   1. [Set torrent share limit](#set-torrent-share-limit)
   1. [Get torrent upload limit](#get-torrent-upload-limit)
   1. [Set torrent upload limit](#set-torrent-upload-limit)
   1. [Set torrent location](#set-torrent-location)
   1. [Set torrent name](#set-torrent-name)
   1. [Set torrent category](#set-torrent-category)
   1. [Get all categories](#get-all-categories)
   1. [Add new category](#add-new-category)
   1. [Edit category](#edit-category)
   1. [Remove categories](#remove-categories)
   1. [Add torrent tags](#add-torrent-tags)
   1. [Remove torrent tags](#remove-torrent-tags)
   1. [Get all tags](#get-all-tags)
   1. [Create tags](#create-tags)
   1. [Delete tags](#delete-tags)
   1. [Set automatic torrent management](#set-automatic-torrent-management)
   1. [Toggle sequential download](#toggle-sequential-download)
   1. [Set first/last piece priority](#set-firstlast-piece-priority)
   1. [Set force start](#set-force-start)
   1. [Set super seeding](#set-super-seeding)
   1. [Rename file](#rename-file)
   1. [Rename folder](#rename-folder)
1. [RSS (experimental)](#rss-experimental)
   1. [Add folder](#add-folder)
   1. [Add feed](#add-feed)
   1. [Remove item](#remove-item)
   1. [Move item](#move-item)
   1. [Get all items](#get-all-items)
   1. [Mark as read](#mark-as-read)
   1. [Refresh item](#refresh-item)
   1. [Set auto-downloading rule](#set-auto-downloading-rule)
   1. [Rename auto-downloading rule](#rename-auto-downloading-rule)
   1. [Remove auto-downloading rule](#remove-auto-downloading-rule)
   1. [Get all auto-downloading rules](#get-all-auto-downloading-rules)
   1. [Get all articles matching a rule](#get-all-articles-matching-a-rule)
1. [Search](#search)
   1. [Start search](#start-search)
   1. [Stop search](#stop-search)
   1. [Get search status](#get-search-status)
   1. [Get search results](#get-search-results)
   1. [Delete search](#delete-search)
   1. [Get search plugins](#get-search-plugins)
   1. [Install search plugin](#install-search-plugin)
   1. [Uninstall search plugin](#uninstall-search-plugin)
   1. [Enable search plugin](#enable-search-plugin)
   1. [Update search plugins](#update-search-plugins)
1. [WebAPI versioning](#webapi-versioning)

***

# Changes #

## API v2.0 ##

- New version naming scheme: X.Y.Z (where X - major version, Y - minor version, Z - release version)
- New API paths. All API methods are under `api/vX/` (where X is API major version)
- API methods are under new scopes

## API v2.0.1 ##

- Add `hashes` field to `/torrents/info` ([#8782](https://github.com/qbittorrent/qBittorrent/pull/8782))
- Add `/torrents/setShareLimits/` method ([#8598](https://github.com/qbittorrent/qBittorrent/pull/8598))

## API v2.0.2 ##

- Add `/torrents/reannounce` method ([#9229](https://github.com/qbittorrent/qBittorrent/pull/9229))

## API v2.1.0 ##

- Change `/sync/maindata` `categories` field from `array` to `object` ([#9228](https://github.com/qbittorrent/qBittorrent/pull/9228))
- Add `savePath` field to `/torrents/createCategory` ([#9228](https://github.com/qbittorrent/qBittorrent/pull/9228)). This method now requires the category to already exist and will not create new categories.
- Add `/torrents/editCategory` method ([#9228](https://github.com/qbittorrent/qBittorrent/pull/9228))

## API v2.1.1 ##

- Add `/torrents/categories` method ([#9586](https://github.com/qbittorrent/qBittorrent/pull/9586))
- Add `/search/` methods ([#8584](https://github.com/qbittorrent/qBittorrent/pull/8584))
- Add `free_space_on_disk` field to `/sync/maindata` ([#8217](https://github.com/qbittorrent/qBittorrent/pull/8217))

## API v2.2.0 ##

- Add `/torrents/editTracker` and `/torrents/removeTracker` methods ([#9375](https://github.com/qbittorrent/qBittorrent/pull/9375))
- Add `tier`, `num_seeds`, `num_leeches`, and `num_downloaded` fields to `/torrents/trackers` ([#9375](https://github.com/qbittorrent/qBittorrent/pull/9375))
- Change `status` field from translated string to an integer for `/torrents/trackers` ([#9375](https://github.com/qbittorrent/qBittorrent/pull/9375))
- Change `/torrents/filePrio` `id` field to accept multiple ids ([#9541](https://github.com/qbittorrent/qBittorrent/pull/9541))
- Throw additional errors for failed requests to `/torrents/filePrio` ([#9541](https://github.com/qbittorrent/qBittorrent/pull/9541))
- Add `autoTMM` field to `/torrents/add` ([#9752](https://github.com/qbittorrent/qBittorrent/pull/9752))
- Add various fields to `/app/getPreferences` and `/app/setPreferences` (`create_subfolder_enabled`, `start_paused_enabled`, `auto_delete_mode`, `preallocate_all`, `incomplete_files_ext`, `auto_tmm_enabled`, `torrent_changed_tmm_enabled`, `save_path_changed_tmm_enabled`, `category_changed_tmm_enabled`, `mail_notification_sender`, `limit_lan_peers`, `slow_torrent_dl_rate_threshold`, `slow_torrent_ul_rate_threshold`, `slow_torrent_inactive_timer`, `alternative_webui_enabled`, `alternative_webui_path`) ([#9752](https://github.com/qbittorrent/qBittorrent/pull/9752))

## API v2.2.1 ##

- Add `rss/refreshItem` ([#11067](https://github.com/qbittorrent/qBittorrent/pull/11067))

## API v2.3.0 ##

- Remove `web_ui_password` field from `/app/preferences`, this field is still writable in `/app/setPreferences` method ([#9942](https://github.com/qbittorrent/qBittorrent/pull/9942))
- Add `/app/buildInfo` method ([#10096](https://github.com/qbittorrent/qBittorrent/pull/10096))
- Always use `/` as path separator in `/torrents/files` response ([#10153](https://github.com/qbittorrent/qBittorrent/pull/10153/))
- Add `/torrents/addPeers` and `/transfer/banPeers` methods ([#10158](https://github.com/qbittorrent/qBittorrent/pull/10158))
- Add `/torrents/addTags`, `/torrents/removeTags`, `/torrents/tags`, `/torrents/createTags`, `/torrents/deleteTags` methods ([#10527](https://github.com/qbittorrent/qBittorrent/pull/10527))

## API v2.4.0 ##

- Add `/torrents/renameFile` method ([#11029](https://github.com/qbittorrent/qBittorrent/pull/11029))

## API v2.4.1 ##

- Add `stalled`, `stalled_uploading` and `stalled_downloading` as possible values for the `filter` parameter in `/torrents/info` ([#11825](https://github.com/qbittorrent/qBittorrent/pull/11825))
- Add various fields to `/app/preferences` and `/app/setPreferences` (`piece_extent_affinity`, `web_ui_secure_cookie_enabled`, `web_ui_max_auth_fail_count`, `web_ui_ban_duration`, `stop_tracker_timeout`) ([#11781](https://github.com/qbittorrent/qBittorrent/pull/11781), [#11726](https://github.com/qbittorrent/qBittorrent/pull/11726), [#12004](https://github.com/qbittorrent/qBittorrent/pull/12004), [#11834](https://github.com/qbittorrent/qBittorrent/pull/11834))

## API v2.5.0 ##
- Removes `enable_super_seeding` as fields from `/app/preferences` and `/app/setPreferences`  ([#12423](https://github.com/qbittorrent/qBittorrent/pull/12423))

## API v2.5.1 ##
- Add `web_ui_use_custom_http_headers_enabled`, `web_ui_custom_http_headers`, `rss_download_repack_proper_episodes` and `rss_smart_episode_filters` as fields to `/app/preferences` and `/app/setPreferences` ([#12579](https://github.com/qbittorrent/qBittorrent/pull/12579), [#12549](https://github.com/qbittorrent/qBittorrent/pull/12549))
- Add `/rss/markAsRead` and `/rss/matchingArticles` methods ([#12549](https://github.com/qbittorrent/qBittorrent/pull/12549))

## API v2.6.0 ##
- Removed `/search/categories` method and modified `/search/plugins` method's response ([#12705](https://github.com/qbittorrent/qBittorrent/pull/12705))

## API v2.6.1 ##
- Exposed `contentPath` via the `content_path` field in the response to `/torrents/info` ([#13625](https://github.com/qbittorrent/qBittorrent/pull/13625))

## API v2.6.2 ##
- Added `tags` optional field to `/torrents/add` ([#13882](https://github.com/qbittorrent/qBittorrent/pull/13882))

## API v2.8.0 ##
- Added `/torrents/renameFolder` method and modified `/torrents/renameFile` method's parameters ([#13995](https://github.com/qbittorrent/qBittorrent/pull/13995))

Note that this change was released in qBittorrent v4.3.3, but the WebAPI version was incorrectly set to v2.7.0 (see [#14275](https://github.com/qbittorrent/qBittorrent/pull/14275#issuecomment-766310862) for details)

## API v2.8.1 ##
- Added `ratioLimit` and `seedingTimeLimit` optional fields to `/torrents/add` ([#14519](https://github.com/qbittorrent/qBittorrent/pull/14519))
- Added `seeding_time` field to `/torrents/info` ([#14554](https://github.com/qbittorrent/qBittorrent/pull/14554))

## API v2.8.2 ##
- Added `indexes` optional parameter to `/torrents/files` ([#14795](https://github.com/qbittorrent/qBittorrent/pull/14795))
- Added `index` field to `/torrents/files` response ([#14795](https://github.com/qbittorrent/qBittorrent/pull/14795))

## API v2.8.3 ##
- Added `tag` optional parameter to `/torrents/info` ([#15152](https://github.com/qbittorrent/qBittorrent/pull/15152))

# General Information #

- All API methods are under `/api/v2/APIName/methodName`, where `APIName` is a certain subgroup of API methods whose functionality is related.
- Either `GET` or `POST` can be used as the request type for all API methods.
- All API methods require [authentication](#authentication) (except the `/api/v2/auth/login` method itself, obviously).

# Authentication #

All Authentication API methods are under "auth", e.g.: `/api/v2/auth/methodName`.

qBittorrent uses cookie-based authentication.

## Login ##

Name: `login`

**Parameters:**

Parameter                         | Type    | Description
----------------------------------|---------|------------
`username`                        | string  | Username used to access the WebUI
`password`                        | string  | Password used to access the WebUI

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
403                               | User's IP is banned for too many failed login attempts
200                               | All other scenarios

Upon success, the response will contain a cookie with your SID. You must supply the cookie whenever you want to perform an operation that requires authentication.

Example showing how to login and execute a command that requires authentication using `curl`:

```sh
$ curl -i --header 'Referer: http://localhost:8080' --data 'username=admin&password=adminadmin' http://localhost:8080/api/v2/auth/login
HTTP/1.1 200 OK
Content-Encoding:
Content-Length: 3
Content-Type: text/plain; charset=UTF-8
Set-Cookie: SID=hBc7TxF76ERhvIw0jQQ4LZ7Z1jQUV0tQ; path=/
$ curl http://localhost:8080/api/v2/torrents/info --cookie "SID=hBc7TxF76ERhvIw0jQQ4LZ7Z1jQUV0tQ"
```

Note: Set `Referer` or `Origin` header to the exact same domain and port as used in the HTTP query `Host` header.

## Logout ##

Name: `logout`

**Parameters:**

None

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

# Application #

All Application API methods are under "app", e.g.: `/api/v2/app/methodName`.

## Get application version ##

Name: `version`

**Parameters:**

None

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

The response is a string with the application version, e.g. `v4.1.3`

## Get API version ##

Name: `webapiVersion`

**Parameters:**

None

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

The response is a string with the WebAPI version, e.g. `2.0`

## Get build info ##

Name: `buildInfo`

**Parameters:**

None

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios- see JSON below

The response is a JSON object containing the following fields

Property     | Type    | Description
-------------|---------|------------
`qt`         | string  | QT version
`libtorrent` | string  | libtorrent version
`boost`      | string  | Boost version
`openssl`    | string  | OpenSSL version
`bitness`    | int     | Application bitness (e.g. 64-bit)

## Shutdown application ##

Name: `shutdown`

**Parameters:**

None

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Get application preferences ##

Name: `preferences`

**Parameters:**

None

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios- see JSON below

The response is a JSON object with several fields (key-value) pairs representing the application's settings. The contents may vary depending on which settings are present in qBittorrent.ini.

Property                                 | Type    | Description
-----------------------------------------|---------|------------
`locale` _optional_                                 | string  | Currently selected language (e.g. en_GB for English)
`create_subfolder_enabled` _optional_               | bool    | True if a subfolder should be created when adding a torrent
`start_paused_enabled` _optional_                   | bool    | True if torrents should be added in a Paused state
`auto_delete_mode` _optional_                       | integer | TODO
`preallocate_all` _optional_                        | bool    | True if disk space should be pre-allocated for all files
`incomplete_files_ext` _optional_                   | bool    | True if ".!qB" should be appended to incomplete files
`auto_tmm_enabled` _optional_                       | bool    | True if Automatic Torrent Management is enabled by default
`torrent_changed_tmm_enabled` _optional_            | bool    | True if torrent should be relocated when its Category changes
`save_path_changed_tmm_enabled` _optional_          | bool    | True if torrent should be relocated when the default save path changes
`category_changed_tmm_enabled` _optional_           | bool    | True if torrent should be relocated when its Category's save path changes
`save_path` _optional_                              | string  | Default save path for torrents, separated by slashes
`temp_path_enabled` _optional_                      | bool    | True if folder for incomplete torrents is enabled
`temp_path` _optional_                              | string  | Path for incomplete torrents, separated by slashes
`scan_dirs` _optional_                              | object  | scan_dirs object see table below. Property: directory to watch for torrent files, value: where torrents loaded from this directory should be downloaded to (see list of possible values below). Slashes are used as path separators; multiple key/value pairs can be specified
`export_dir` _optional_                             | string  | Path to directory to copy .torrent files to. Slashes are used as path separators
`export_dir_fin` _optional_                         | string  | Path to directory to copy .torrent files of completed downloads to. Slashes are used as path separators
`mail_notification_enabled` _optional_              | bool    | True if e-mail notification should be enabled
`mail_notification_sender` _optional_               | string  | e-mail where notifications should originate from
`mail_notification_email` _optional_                | string  | e-mail to send notifications to
`mail_notification_smtp` _optional_                 | string  | smtp server for e-mail notifications
`mail_notification_ssl_enabled` _optional_          | bool    | True if smtp server requires SSL connection
`mail_notification_auth_enabled` _optional_         | bool    | True if smtp server requires authentication
`mail_notification_username` _optional_             | string  | Username for smtp authentication
`mail_notification_password` _optional_             | string  | Password for smtp authentication
`autorun_enabled` _optional_                        | bool    | True if external program should be run after torrent has finished downloading
`autorun_program` _optional_                        | string  | Program path/name/arguments to run if `autorun_enabled` is enabled; path is separated by slashes; you can use `%f` and `%n` arguments, which will be expanded by qBittorent as path_to_torrent_file and torrent_name (from the GUI; not the .torrent file name) respectively
`queueing_enabled` _optional_                       | bool    | True if torrent queuing is enabled
`max_active_downloads` _optional_                   | integer | Maximum number of active simultaneous downloads
`max_active_torrents` _optional_                    | integer | Maximum number of active simultaneous downloads and uploads
`max_active_uploads` _optional_                     | integer | Maximum number of active simultaneous uploads
`dont_count_slow_torrents` _optional_               | bool    | If true torrents w/o any activity (stalled ones) will not be counted towards `max_active_*` limits; see [dont_count_slow_torrents](https://www.libtorrent.org/reference-Settings.html#dont_count_slow_torrents) for more information
`slow_torrent_dl_rate_threshold` _optional_         | integer | Download rate in KiB/s for a torrent to be considered "slow"
`slow_torrent_ul_rate_threshold` _optional_         | integer | Upload rate in KiB/s for a torrent to be considered "slow"
`slow_torrent_inactive_timer` _optional_            | integer | Seconds a torrent should be inactive before considered "slow"
`max_ratio_enabled` _optional_                      | bool    | True if share ratio limit is enabled
`max_ratio` _optional_                              | float   | Get the global share ratio limit
`max_ratio_act` _optional_                          | object | max_ratio_act object see table below. Action performed when a torrent reaches the maximum share ratio. See list of possible values here below.
`listen_port` _optional_                            | integer | Port for incoming connections
`upnp` _optional_                                   | bool    | True if UPnP/NAT-PMP is enabled
`random_port` _optional_                            | bool    | True if the port is randomly selected
`dl_limit` _optional_                               | integer | Global download speed limit in KiB/s; `-1` means no limit is applied
`up_limit` _optional_                               | integer | Global upload speed limit in KiB/s; `-1` means no limit is applied
`max_connec` _optional_                             | integer | Maximum global number of simultaneous connections
`max_connec_per_torrent` _optional_                 | integer | Maximum number of simultaneous connections per torrent
`max_uploads` _optional_                            | integer | Maximum number of upload slots
`max_uploads_per_torrent` _optional_                | integer | Maximum number of upload slots per torrent
`stop_tracker_timeout` _optional_                   | integer | Timeout in seconds for a `stopped` announce request to trackers
`enable_piece_extent_affinity` _optional_           | bool    | True if the advanced libtorrent option `piece_extent_affinity` is enabled
`bittorrent_protocol` _optional_                    | object | bittorrent_protocol object see table below Bittorrent Protocol to use (see list of possible values below)
`limit_utp_rate` _optional_                         | bool    | True if `[du]l_limit` should be applied to uTP connections; this option is only available in qBittorent built against libtorrent version 0.16.X and higher
`limit_tcp_overhead` _optional_                     | bool    | True if `[du]l_limit` should be applied to estimated TCP overhead (service data: e.g. packet headers)
`limit_lan_peers` _optional_                        | bool    | True if `[du]l_limit` should be applied to peers on the LAN
`alt_dl_limit` _optional_                           | integer | Alternative global download speed limit in KiB/s
`alt_up_limit` _optional_                           | integer | Alternative global upload speed limit in KiB/s
`scheduler_enabled` _optional_                      | bool    | True if alternative limits should be applied according to schedule
`schedule_from_hour` _optional_                     | integer | Scheduler starting hour
`schedule_from_min` _optional_                      | integer | Scheduler starting minute
`schedule_to_hour` _optional_                       | integer | Scheduler ending hour
`schedule_to_min` _optional_                        | integer | Scheduler ending minute
`scheduler_days` _optional_                         | object | scheduler_days object see table below. See possible values here below
`dht` _optional_                                    | bool    | True if DHT is enabled
`pex` _optional_                                    | bool    | True if PeX is enabled
`lsd` _optional_                                    | bool    | True if LSD is enabled
`encryption` _optional_                             | object | encryption object see table below. See list of possible values here below
`anonymous_mode` _optional_                         | bool    | If true anonymous mode will be enabled; read more [here](Anonymous-Mode); this option is only available in qBittorent built against libtorrent version 0.16.X and higher
`proxy_type` _optional_                             | integer | proxy_type object see table below. See list of possible values here below
`proxy_ip` _optional_                               | string  | Proxy IP address or domain name
`proxy_port` _optional_                             | integer | Proxy port
`proxy_peer_connections` _optional_                 | bool    | True if peer and web seed connections should be proxified; this option will have any effect only in qBittorent built against libtorrent version 0.16.X and higher
`proxy_auth_enabled` _optional_                     | bool    | True proxy requires authentication; doesn't apply to SOCKS4 proxies
`proxy_username` _optional_                         | string  | Username for proxy authentication
`proxy_password` _optional_                         | string  | Password for proxy authentication
`proxy_torrents_only` _optional_                    | bool    | True if proxy is only used for torrents
`ip_filter_enabled` _optional_                      | bool    | True if external IP filter should be enabled
`ip_filter_path` _optional_                         | string  | Path to IP filter file (.dat, .p2p, .p2b files are supported); path is separated by slashes
`ip_filter_trackers` _optional_                     | bool    | True if IP filters are applied to trackers
`web_ui_domain_list` _optional_                     | string  | Comma-separated list of domains to accept when performing Host header validation
`web_ui_address` _optional_                         | string  | IP address to use for the WebUI
`web_ui_port` _optional_                            | integer | WebUI port
`web_ui_upnp` _optional_                            | bool    | True if UPnP is used for the WebUI port
`web_ui_username` _optional_                        | string  | WebUI username
`web_ui_password` _optional_                        | string  | For API ≥ v2.3.0: Plaintext WebUI password, not readable, write-only. For API < v2.3.0: MD5 hash of WebUI password, hash is generated from the following string: `username:Web UI Access:plain_text_web_ui_password`
`web_ui_csrf_protection_enabled` _optional_         | bool    | True if WebUI CSRF protection is enabled
`web_ui_clickjacking_protection_enabled` _optional_ | bool    | True if WebUI clickjacking protection is enabled
`web_ui_secure_cookie_enabled` _optional_           | bool    | True if WebUI cookie `Secure` flag is enabled
`web_ui_max_auth_fail_count` _optional_             | integer | Maximum number of authentication failures before WebUI access ban
`web_ui_ban_duration` _optional_                    | integer | WebUI access ban duration in seconds
`web_ui_session_timeout` _optional_                 | integer | Seconds until WebUI is automatically signed off
`web_ui_host_header_validation_enabled` _optional_  | bool    | True if WebUI host header validation is enabled
`bypass_local_auth` _optional_                      | bool    | True if authentication challenge for loopback address (127.0.0.1) should be disabled
`bypass_auth_subnet_whitelist_enabled` _optional_   | bool    | True if webui authentication should be bypassed for clients whose ip resides within (at least) one of the subnets on the whitelist
`bypass_auth_subnet_whitelist` _optional_           | string  | (White)list of ipv4/ipv6 subnets for which webui authentication should be bypassed; list entries are separated by commas
`alternative_webui_enabled` _optional_              | bool    | True if an alternative WebUI should be used
`alternative_webui_path` _optional_                 | string  | File path to the alternative WebUI
`use_https` _optional_                              | bool    | True if WebUI HTTPS access is enabled
`ssl_key` _optional_                                | string  | For API < v2.0.1: SSL keyfile contents (this is a not a path)
`ssl_cert` _optional_                               | string  | For API < v2.0.1: SSL certificate contents (this is a not a path)
`web_ui_https_key_path` _optional_                  | string  | For API ≥ v2.0.1: Path to SSL keyfile
`web_ui_https_cert_path` _optional_                 | string  | For API ≥ v2.0.1: Path to SSL certificate
`dyndns_enabled` _optional_                         | bool    | True if server DNS should be updated dynamically
`dyndns_service` _optional_                         | integer | dyndns_service object see table below. See list of possible values here below
`dyndns_username` _optional_                        | string  | Username for DDNS service
`dyndns_password` _optional_                        | string  | Password for DDNS service
`dyndns_domain` _optional_                          | string  | Your DDNS domain name
`rss_refresh_interval` _optional_                   | integer | RSS refresh interval
`rss_max_articles_per_feed` _optional_              | integer | Max stored articles per RSS feed
`rss_processing_enabled` _optional_                 | bool    | Enable processing of RSS feeds
`rss_auto_downloading_enabled` _optional_           | bool    | Enable auto-downloading of torrents from the RSS feeds
`rss_download_repack_proper_episodes` _optional_    | bool    | For API ≥ v2.5.1: Enable downloading of repack/proper Episodes
`rss_smart_episode_filters` _optional_              | string  | For API ≥ v2.5.1: List of RSS Smart Episode Filters
`add_trackers_enabled` _optional_                   | bool    | Enable automatic adding of trackers to new torrents
`add_trackers` _optional_                           | string  | List of trackers to add to new torrent
`web_ui_use_custom_http_headers_enabled` _optional_ | bool    | For API ≥ v2.5.1: Enable custom http headers
`web_ui_custom_http_headers` _optional_             | string  | For API ≥ v2.5.1: List of custom http headers
`max_seeding_time_enabled` _optional_               | bool    | True enables max seeding time 
`max_seeding_time` _optional_                       | integer | Number of minutes to seed a torrent
`announce_ip` _optional_                            | string  | TODO
`announce_to_all_tiers` _optional_                  | bool    | True always announce to all tiers
`announce_to_all_trackers` _optional_               | bool    | True always announce to all trackers in a tier
`async_io_threads` _optional_                       | integer | Number of asynchronous I/O threads
`banned_IPs` _optional_                             | string  | List of banned IPs
`checking_memory_use` _optional_                    | integer | Outstanding memory when checking torrents in MiB
`current_interface_address` _optional_              | string  | IP Address to bind to. Empty String means All addresses
`current_network_interface` _optional_              | string  | Network Interface used
`disk_cache` _optional_                             | integer | Disk cache used in MiB
`disk_cache_ttl` _optional_                         | integer | Disk cache expiry interval in seconds
`embedded_tracker_port` _optional_                  | integer | Port used for embedded tracker
`enable_coalesce_read_write` _optional_             | bool    | True enables coalesce reads & writes
`enable_embedded_tracker` _optional_                | bool    | True enables embedded tracker
`enable_multi_connections_from_same_ip` _optional_  | bool    | True allows multiple connections from the same IP address
`enable_os_cache` _optional_                        | bool    | True enables os cache
`enable_upload_suggestions` _optional_              | bool    | True enables sending of upload piece suggestions
`file_pool_size` _optional_                         | integer | File pool size
`outgoing_ports_max` _optional_                     | integer | Maximal outgoing port (0: Disabled)
`outgoing_ports_min` _optional_                     | integer | Minimal outgoing port (0: Disabled)
`recheck_completed_torrents` _optional_             | bool    | True rechecks torrents on completion
`resolve_peer_countries` _optional_                 | bool    | True resolves peer countries
`save_resume_data_interval` _optional_              | integer | Save resume data interval in min
`send_buffer_low_watermark` _optional_              | integer | Send buffer low watermark in KiB
`send_buffer_watermark` _optional_                  | integer | Send buffer watermark in KiB
`send_buffer_watermark_factor` _optional_           | integer | Send buffer watermark factor in percent
`socket_backlog_size` _optional_                    | integer | Socket backlog size
`upload_choking_algorithm` _optional_               | object | upload_choking_algorithm object see table below. Upload choking algorithm used (see list of possible values below)
`upload_slots_behavior` _optional_                  | object | upload_slots_behavior object see table below. Upload slots behavior used (see list of possible values below)
`upnp_lease_duration` _optional_                    | integer | UPnP lease duration (0: Permanent lease)
`utp_tcp_mixed_mode` _optional_                     | object | utp_tcp_mixed_mode object see table below. μTP-TCP mixed mode algorithm (see list of possible values below)

Possible values of `scan_dirs`:

Value                       | Description
----------------------------|------------
`0`                         | Download to the monitored folder
`1`                         | Download to the default save path
`"/path/to/download/to"`    | Download to this path

Possible values of `scheduler_days`:

Value  | Description
-------|------------
`0`    | Every day
`1`    | Every weekday
`2`    | Every weekend
`3`    | Every Monday
`4`    | Every Tuesday
`5`    | Every Wednesday
`6`    | Every Thursday
`7`    | Every Friday
`8`    | Every Saturday
`9`    | Every Sunday

Possible values of `encryption`:

Value  | Description
-------|------------
`0`    | Prefer encryption
`1`    | Force encryption on
`2`    | Force encryption off

NB: the first options allows you to use both encrypted and unencrypted connections (this is the default); other options are mutually exclusive: e.g. by forcing encryption on you won't be able to use unencrypted connections and vice versa.

Possible values of `proxy_type`:

Value | Description
------|------------
`-1`  | Proxy is disabled
`1`   | HTTP proxy without authentication
`2`   | SOCKS5 proxy without authentication
`3`   | HTTP proxy with authentication
`4`   | SOCKS5 proxy with authentication
`5`   | SOCKS4 proxy without authentication

Possible values of `dyndns_service`:

Value  | Description
-------|------------
`0`    | Use DyDNS
`1`    | Use NOIP

Possible values of `max_ratio_act`:

Value | Description
------|------------
`0`   | Pause torrent
`1`   | Remove torrent

Possible values of `bittorrent_protocol`:

Value  | Description
-------|------------
`0`    | TCP and μTP
`1`    | TCP
`2`    | μTP

Possible values of `upload_choking_algorithm`:

Value  | Description
-------|------------
`0`    | Round-robin
`1`    | Fastest upload
`2`    | Anti-leech

Possible values of `upload_slots_behavior`:

Value  | Description
-------|------------
`0`    | Fixed slots
`1`    | Upload rate based

Possible values of `utp_tcp_mixed_mode`:

Value  | Description
-------|------------
`0`    | Prefer TCP
`1`    | Peer proportional

Example:

```JSON
{
    "add_trackers": "",
    "add_trackers_enabled": false,
    "alt_dl_limit": 10240,
    "alt_up_limit": 10240,
    "alternative_webui_enabled": false,
    "alternative_webui_path": "/home/user/Documents/qbit-webui",
    "announce_ip": "",
    "announce_to_all_tiers": true,
    "announce_to_all_trackers": false,
    "anonymous_mode": false,
    "async_io_threads": 4,
    "auto_delete_mode": 0,
    "auto_tmm_enabled": false,
    "autorun_enabled": false,
    "autorun_program": "",
    "banned_IPs": "",
    "bittorrent_protocol": 0,
    "bypass_auth_subnet_whitelist": "",
    "bypass_auth_subnet_whitelist_enabled": false,
    "bypass_local_auth": false,
    "category_changed_tmm_enabled": false,
    "checking_memory_use": 32,
    "create_subfolder_enabled": true,
    "current_interface_address": "",
    "current_network_interface": "",
    "dht": true,
    "disk_cache": -1,
    "disk_cache_ttl": 60,
    "dl_limit": 0,
    "dont_count_slow_torrents": false,
    "dyndns_domain": "changeme.dyndns.org",
    "dyndns_enabled": false,
    "dyndns_password": "",
    "dyndns_service": 0,
    "dyndns_username": "",
    "embedded_tracker_port": 9000,
    "enable_coalesce_read_write": false,
    "enable_embedded_tracker": false,
    "enable_multi_connections_from_same_ip": false,
    "enable_os_cache": true,
    "enable_piece_extent_affinity": false,
    "enable_upload_suggestions": false,
    "encryption": 0,
    "export_dir": "/home/user/Downloads/all",
    "export_dir_fin": "/home/user/Downloads/completed",
    "file_pool_size": 40,
    "incomplete_files_ext": false,
    "ip_filter_enabled": false,
    "ip_filter_path": "",
    "ip_filter_trackers": false,
    "limit_lan_peers": true,
    "limit_tcp_overhead": false,
    "limit_utp_rate": true,
    "listen_port": 58925,
    "locale": "en",
    "lsd": true,
    "mail_notification_auth_enabled": false,
    "mail_notification_email": "",
    "mail_notification_enabled": false,
    "mail_notification_password": "",
    "mail_notification_sender": "qBittorrent_notification@example.com",
    "mail_notification_smtp": "smtp.changeme.com",
    "mail_notification_ssl_enabled": false,
    "mail_notification_username": "",
    "max_active_downloads": 3,
    "max_active_torrents": 5,
    "max_active_uploads": 3,
    "max_connec": 500,
    "max_connec_per_torrent": 100,
    "max_ratio": -1,
    "max_ratio_act": 0,
    "max_ratio_enabled": false,
    "max_seeding_time": -1,
    "max_seeding_time_enabled": false,
    "max_uploads": -1,
    "max_uploads_per_torrent": -1,
    "outgoing_ports_max": 0,
    "outgoing_ports_min": 0,
    "pex": true,
    "preallocate_all": false,
    "proxy_auth_enabled": false,
    "proxy_ip": "0.0.0.0",
    "proxy_password": "",
    "proxy_peer_connections": false,
    "proxy_port": 8080,
    "proxy_torrents_only": false,
    "proxy_type": 0,
    "proxy_username": "",
    "queueing_enabled": false,
    "random_port": false,
    "recheck_completed_torrents": false,
    "resolve_peer_countries": true,
    "rss_auto_downloading_enabled":true,
    "rss_download_repack_proper_episodes":true,
    "rss_max_articles_per_feed":50,
    "rss_processing_enabled":true,
    "rss_refresh_interval":30,
    "rss_smart_episode_filters":"s(\\d+)e(\\d+)\n(\\d+)x(\\d+)\n(\\d{4}[.\\-]\\d{1,2}[.\\-]\\d{1,2})",
    "save_path": "/home/user/Downloads/",
    "save_path_changed_tmm_enabled": false,
    "save_resume_data_interval": 60,
    "scan_dirs":
    {
        "/home/user/Downloads/incoming/games": 0,
        "/home/user/Downloads/incoming/movies": 1,
    },
    "schedule_from_hour": 8,
    "schedule_from_min": 0,
    "schedule_to_hour": 20,
    "schedule_to_min": 0,
    "scheduler_days": 0,
    "scheduler_enabled": false,
    "send_buffer_low_watermark": 10,
    "send_buffer_watermark": 500,
    "send_buffer_watermark_factor": 50,
    "slow_torrent_dl_rate_threshold": 2,
    "slow_torrent_inactive_timer": 60,
    "slow_torrent_ul_rate_threshold": 2,
    "socket_backlog_size": 30,
    "start_paused_enabled": false,
    "stop_tracker_timeout": 1,
    "temp_path": "/home/user/Downloads/temp",
    "temp_path_enabled": false,
    "torrent_changed_tmm_enabled": true,
    "up_limit": 0,
    "upload_choking_algorithm": 1,
    "upload_slots_behavior": 0,
    "upnp": true,
    "use_https": false,
    "utp_tcp_mixed_mode": 0,
    "web_ui_address": "*",
    "web_ui_ban_duration": 3600,
    "web_ui_clickjacking_protection_enabled": true,
    "web_ui_csrf_protection_enabled": true,
    "web_ui_custom_http_headers": "",
    "web_ui_domain_list": "*",
    "web_ui_host_header_validation_enabled": true,
    "web_ui_https_cert_path": "",
    "web_ui_https_key_path": "",
    "web_ui_max_auth_fail_count": 5,
    "web_ui_port": 8080,
    "web_ui_secure_cookie_enabled": true,
    "web_ui_session_timeout": 3600,
    "web_ui_upnp": false,
    "web_ui_use_custom_http_headers_enabled": false,
    "web_ui_username": "admin"
}
```

## Set application preferences ##

Name: `setPreferences`

**Parameters:**

A json object with key-value pairs of the settings you want to change and their new values.

Example:

```JSON
json={"save_path":"C:/Users/Dayman/Downloads","queueing_enabled":false,"scan_dirs":{"C:/Games": 0,"D:/Downloads": 1}}
```

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

**Notes**:

  1. There is no need to pass all possible preferences' `token:value` pairs if you only want to change one option
  1. Paths in `scan_dirs` must exist, otherwise this option will have no effect
  1. String values must be quoted; integer and boolean values must never be quoted

For a list of possible preference options see [Get application preferences](#get-application-preferences)

## Get default save path ##

Name: `defaultSavePath`

**Parameters:**

None

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

The response is a string with the default save path, e.g. `C:/Users/Dayman/Downloads`.

# Log #

All Log API methods are under "log", e.g.: `/api/v2/log/methodName`.

## Get log ##

Name: `main`

**Parameters:**

Parameter       | Type    | Description
----------------|---------|------------
`normal`        | bool    | Include normal messages (default: `true`)
`info`          | bool    | Include info messages (default: `true`)
`warning`       | bool    | Include warning messages (default: `true`)
`critical`      | bool    | Include critical messages (default: `true`)
`last_known_id` | integer | Exclude messages with "message id" <= `last_known_id` (default: `-1`)

Example:

```http
/api/v2/log/main?normal=true&info=true&warning=true&critical=true&last_known_id=-1
```

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios- see JSON below

The response is a JSON array in which each element is an entry of the log.

Each element of the array has the following properties:

Property    | Type    | Description
------------|---------|------------
`id`        | integer | ID of the message
`message`   | string  | Text of the message
`timestamp` | integer | Milliseconds since epoch
`type`      | integer | Type of the message: Log::NORMAL: `1`, Log::INFO: `2`, Log::WARNING: `4`, Log::CRITICAL: `8`

Example:

```JSON
[
    {
        "id":0,
        "message":"qBittorrent v3.4.0 started",
        "timestamp":1507969127860,
        "type":1
    },
    {
        "id":1,
        "message":"qBittorrent is trying to listen on any interface port: 19036",
        "timestamp":1507969127869,
        "type":2
    },
    {
        "id":2,
        "message":"Peer ID: -qB3400-",
        "timestamp":1507969127870,
        "type":1
    },
    {
        "id":3,
        "message":"HTTP User-Agent is 'qBittorrent/3.4.0'",
        "timestamp":1507969127870,
        "type":1
    },
    {
        "id":4,
        "message":"DHT support [ON]",
        "timestamp":1507969127871,
        "type":2
    },
    {
        "id":5,
        "message":"Local Peer Discovery support [ON]",
        "timestamp":1507969127871,
        "type":2
    },
    {
        "id":6,
        "message":"PeX support [ON]",
        "timestamp":1507969127871,
        "type":2
    },
    {
        "id":7,
        "message":"Anonymous mode [OFF]",
        "timestamp":1507969127871,
        "type":2
    },
    {
        "id":8,
        "message":"Encryption support [ON]",
        "timestamp":1507969127871,
        "type":2
    },
    {
        "id":9,
        "message":"Embedded Tracker [OFF]",
        "timestamp":1507969127871,
        "type":2
    },
    {
        "id":10,
        "message":"UPnP / NAT-PMP support [ON]",
        "timestamp":1507969127873,
        "type":2
    },
    {
        "id":11,
        "message":"Web UI: Now listening on port 8080",
        "timestamp":1507969127883,
        "type":1
    },
    {
        "id":12,
        "message":"Options were saved successfully.",
        "timestamp":1507969128055,
        "type":1
    },
    {
        "id":13,
        "message":"qBittorrent is successfully listening on interface :: port: TCP/19036",
        "timestamp":1507969128270,
        "type":2
    },
    {
        "id":14,
        "message":"qBittorrent is successfully listening on interface 0.0.0.0 port: TCP/19036",
        "timestamp":1507969128271,
        "type":2
    },
    {
        "id":15,
        "message":"qBittorrent is successfully listening on interface 0.0.0.0 port: UDP/19036",
        "timestamp":1507969128272,
        "type":2
    }
]
```

## Get peer log ##

Name: `peers`

**Parameters:**

Parameter       | Type    | Description
----------------|---------|------------
`last_known_id` | integer | Exclude messages with "message id" <= `last_known_id` (default: `-1`)

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios- see JSON below

The response a JSON array. Each element of the array of objects (each object is the information relative to a peer) containing the following fields

Property    | Type    | Description
------------|---------|------------
`id`        | integer | ID of the peer
`ip`        | string  | IP of the peer
`timestamp` | integer | Milliseconds since epoch
`blocked`   | boolean | Whether or not the peer was blocked
`reason`    | string  | Reason of the block

# Sync #

Sync API implements requests for obtaining changes since the last request.
All Sync API methods are under "sync", e.g.: `/api/v2/sync/methodName`.

## Get main data ##

Name: `maindata`

**Parameters:**

Parameter | Type    | Description
----------|---------|------------
`rid`     | integer | Response ID. If not provided, `rid=0` will be assumed. If the given `rid` is different from the one of last server reply, `full_update` will be `true` (see the server reply details for more info)

Example:

```http
/api/v2/sync/maindata?rid=14
```

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios- see JSON below

The response is a JSON object with the following possible fields

Property                        | Type      | Description
--------------------------------|-----------|------------
`rid`                           | integer   | Response ID
`full_update` _optional_         | bool      | Whether the response contains all the data or partial data
`torrents` _optional_            | object    | Property: torrent hash, value: same as [torrent list](#get-torrent-list), map from string to torrents object
`torrents_removed` _optional_    | array     | List of hashes of torrents removed since last request
`categories` _optional_          | object    | Info for categories added since last request, map from string to categories object
`categories_removed` _optional_  | array     | List of categories removed since last request
`tags` _optional_                | array     | List of tags added since last request
`tags_removed` _optional_        | array     | List of tags removed since last request
`server_state` _optional_        | object    | `server_state` object see table below

Example:

```JSON
{
    "rid":15,
    "torrents":
    {
        "8c212779b4abde7c6bc608063a0d008b7e40ce32":
        {
            "state":"pausedUP"
        }
    }
}
```

**ServerState object:**

Property                      | Type    | Description
------------------------------|---------|------------
`average_time_queue`          | integer | Average time queue
`dl_info_data`                | number  | Download info data
`dl_info_speed`               | number  | Download info speed
`queued_io_jobs`              | integer | Queued io jobs
`total_buffers_size`          | number  | Total buffers size
`total_peer_connections`      | integer | Total peer connections

**Categories object:**

Property                      | Type    | Description
------------------------------|---------|------------
`name`                        | string  | Category name
`savePath`                    | string  | Save path

**Torrents object:**

Property                        | Type      | Description
--------------------------------|-----------|------------
`added_on`_optional_            | integer   | Time (Unix Epoch) when the torrent was added to the client
`amount_left`_optional_         | integer   | Amount of data left to download (bytes)
`auto_tmm`_optional_            | bool      | Whether this torrent is managed by Automatic Torrent Management
`availability`_optional_        | float     | Percentage of file pieces currently available
`category`_optional_            | string    | Category of the torrent
`completed`_optional_           | integer   | Amount of transfer data completed (bytes)
`completion_on`_optional_       | integer   | Time (Unix Epoch) when the torrent completed
`content_path`_optional_        | string    | Absolute path of torrent content (root path for multifile torrents, absolute file path for singlefile torrents)
`dl_limit`_optional_            | integer   | Torrent download speed limit (bytes/s). `-1` if ulimited.
`dlspeed`_optional_             | integer   | Torrent download speed (bytes/s)
`downloaded`_optional_          | integer   | Amount of data downloaded
`downloaded_session`_optional_  | integer   | Amount of data downloaded this session
`eta`_optional_                 | integer   | Torrent ETA (seconds)
`f_l_piece_prio`_optional_      | bool      | True if first last piece are prioritized
`force_start`_optional_         | bool      | True if force start is enabled for this torrent
`hash`_optional_                | string    | Torrent hash
`last_activity`_optional_       | integer   | Last time (Unix Epoch) when a chunk was downloaded/uploaded
`magnet_uri`_optional_          | string    | Magnet URI corresponding to this torrent
`max_ratio`_optional_           | float     | Maximum share ratio until torrent is stopped from seeding/uploading
`max_seeding_time`_optional_    | integer   | Maximum seeding time (seconds) until torrent is stopped from seeding
`name`_optional_                | string    | Torrent name
`num_complete`_optional_        | integer   | Number of seeds in the swarm
`num_incomplete`_optional_      | integer   | Number of leechers in the swarm
`num_leechs`_optional_          | integer   | Number of leechers connected to
`num_seeds`_optional_           | integer   | Number of seeds connected to
`priority`_optional_            | integer   | Torrent priority. Returns -1 if queuing is disabled or torrent is in seed mode
`progress`_optional_            | float     | Torrent progress (percentage/100)
`ratio`_optional_               | float     | Torrent share ratio. Max ratio value: 9999.
`ratio_limit`_optional_         | float     | TODO (what is different from `max_ratio`?)
`save_path`_optional_           | string    | Path where this torrent's data is stored
`seeding_time`_optional_        | integer   | Torrent elapsed time while complete (seconds)
`seeding_time_limit`_optional_  | integer   | TODO (what is different from `max_seeding_time`?) seeding_time_limit is a per torrent setting, when Automatic Torrent Management is disabled, furthermore then max_seeding_time is set to seeding_time_limit for this torrent. If Automatic Torrent Management is enabled, the value is -2. And if max_seeding_time is unset it have a default value -1.
`seen_complete`_optional_       | integer   | Time (Unix Epoch) when this torrent was last seen complete
`seq_dl`_optional_              | bool      | True if sequential download is enabled
`size`_optional_                | integer   | Total size (bytes) of files selected for download
`state`_optional_               | string    | Torrent state. See table here below for the possible values
`super_seeding`_optional_       | bool      | True if super seeding is enabled
`tags`_optional_                | string    | Comma-concatenated tag list of the torrent
`time_active`_optional_         | integer   | Total active time (seconds)
`total_size`_optional_          | integer   | Total size (bytes) of all file in this torrent (including unselected ones)
`tracker`_optional_             | string    | The first tracker with working status. Returns empty string if no tracker is working.
`up_limit`_optional_            | integer   | Torrent upload speed limit (bytes/s). `-1` if ulimited.
`uploaded`_optional_            | integer   | Amount of data uploaded
`uploaded_session`_optional_    | integer   | Amount of data uploaded this session
`upspeed`_optional_             | integer   | Torrent upload speed (bytes/s)

## Get torrent peers data ##

Name: `torrentPeers`

**Parameters:**

Parameter | Type    | Description
----------|---------|------------
`hash`    | string  | Torrent hash
`rid`     | integer | Response ID. If not provided, `rid=0` will be assumed. If the given `rid` is different from the one of last server reply, `full_update` will be `true` (see the server reply details for more info)

Example:

```http
/api/v2/sync/torrentPeers?hash=8c212779b4abde7c6bc608063a0d008b7e40ce32?rid=14
```

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
404                               | Torrent hash was not found
200                               | All other scenarios- see JSON below

The response is TODO

# Transfer info #

All Transfer info API methods are under "transfer", e.g.: `/api/v2/transfer/methodName`.

## Get global transfer info ##

This method returns info you usually see in qBt status bar.

Name: `info`

**Parameters:**

None

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios- see JSON below

The response is a JSON object with the following fields

Property            | Type    | Description
--------------------|---------|------------
`dl_info_speed`     | integer | Global download rate (bytes/s)
`dl_info_data`      | integer | Data downloaded this session (bytes)
`up_info_speed`     | integer | Global upload rate (bytes/s)
`up_info_data`      | integer | Data uploaded this session (bytes)
`dl_rate_limit`     | integer | Download rate limit (bytes/s)
`up_rate_limit`     | integer | Upload rate limit (bytes/s)
`dht_nodes`         | integer | DHT nodes connected to
`connection_status` | string  | Connection status. See possible values here below

In addition to the above in partial data requests (see [Get partial data](#get-partial-data) for more info):

Property               | Type    | Description
-----------------------|---------|------------
`queueing`             | bool    | True if torrent queueing is enabled
`use_alt_speed_limits` | bool    | True if alternative speed limits are enabled
`refresh_interval`     | integer | Transfer list refresh interval (milliseconds)

Possible values of `connection_status`:

Value               |
--------------------|
`connected`         |
`firewalled`        |
`disconnected`      |

Example:

```JSON
{
    "connection_status":"connected",
    "dht_nodes":386,
    "dl_info_data":681521119,
    "dl_info_speed":0,
    "dl_rate_limit":0,
    "up_info_data":10747904,
    "up_info_speed":0,
    "up_rate_limit":1048576
}
```

## Get alternative speed limits state ##

Name: `speedLimitsMode`

**Parameters:**

None

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

The response is `1` if alternative speed limits are enabled, `0` otherwise.

## Toggle alternative speed limits ##

Name: `toggleSpeedLimitsMode`

**Parameters:**

None

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Get global download limit ##

Name: `downloadLimit`

**Parameters:**

None

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

The response is the value of current global download speed limit in bytes/second; this value will be zero if no limit is applied.

## Set global download limit ##

Name: `setDownloadLimit`

**Parameters:**

Parameter                         | Type    | Description
----------------------------------|---------|------------
`limit`                           | integer | The global download speed limit to set in bytes/second

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Get global upload limit ##

Name: `uploadLimit`

**Parameters:**

None

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

The response is the value of current global upload speed limit in bytes/second; this value will be zero if no limit is applied.

## Set global upload limit ##

Name: `setUploadLimit`

**Parameters:**

Parameter                         | Type    | Description
----------------------------------|---------|------------
`limit`                           | integer | The global upload speed limit to set in bytes/second

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Ban peers ##

Name: `banPeers`

**Parameters:**

Parameter                         | Type    | Description
----------------------------------|---------|------------
`peers`                           | string  | The peer to ban, or multiple peers separated by a pipe. Each peer is a colon-separated `host:port`

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

# Torrent management #

All Torrent management API methods are under "torrents", e.g.: `/api/v2/torrents/methodName`.

## Get torrent list ##

Name: `info`

**Parameters:**

Parameter             | Type    | Description
----------------------|---------|------------
`filter`  _optional_  | string  | Filter torrent list by state. Allowed state filters: `all`, `downloading`, `seeding`, `completed`, `paused`, `active`, `inactive`, `resumed`, `stalled`, `stalled_uploading`, `stalled_downloading`, `errored`
`category` _optional_ | string  | Get torrents with the given category (empty string means "without category"; no "category" parameter means "any category" <- broken until [#11748](https://github.com/qbittorrent/qBittorrent/issues/11748) is resolved). Remember to URL-encode the category name. For example, `My category` becomes `My%20category`
`tag` _optional_ | string  | Get torrents with the given tag (empty string means "without tag"; no "tag" parameter means "any tag". Remember to URL-encode the category name. For example, `My tag` becomes `My%20tag`
`sort` _optional_     | string  | Sort torrents by given key. They can be sorted using any field of the response (which are documented below) as the sort key.
`reverse` _optional_  | bool    | Enable reverse sorting. Defaults to `false`
`limit` _optional_    | integer | Limit the number of torrents returned
`offset` _optional_   | integer | Set offset (if less than 0, offset from end)
`hashes` _optional_   | string  | Filter by hashes. Can contain multiple hashes separated by a pipe

Example:

```http
/api/v2/torrents/info?filter=downloading&category=sample%20category&sort=ratio
```

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios- see JSON below

The response is a JSON array with the following fields

Property             | Type    | Description
---------------------|---------|------------
`added_on`           | integer | Time (Unix Epoch) when the torrent was added to the client
`amount_left`        | integer | Amount of data left to download (bytes)
`auto_tmm`           | bool    | Whether this torrent is managed by Automatic Torrent Management
`availability`       | float   | Percentage of file pieces currently available
`category`           | string  | Category of the torrent
`completed`          | integer | Amount of transfer data completed (bytes)
`completion_on`      | integer | Time (Unix Epoch) when the torrent completed
`content_path`       | string  | Absolute path of torrent content (root path for multifile torrents, absolute file path for singlefile torrents)
`dl_limit`           | integer | Torrent download speed limit (bytes/s). `-1` if ulimited.
`dlspeed`            | integer | Torrent download speed (bytes/s)
`downloaded`         | integer | Amount of data downloaded
`downloaded_session` | integer | Amount of data downloaded this session
`eta`                | integer | Torrent ETA (seconds)
`f_l_piece_prio`     | bool    | True if first last piece are prioritized
`force_start`        | bool    | True if force start is enabled for this torrent
`hash`               | string  | Torrent hash
`last_activity`      | integer | Last time (Unix Epoch) when a chunk was downloaded/uploaded
`magnet_uri`         | string  | Magnet URI corresponding to this torrent
`max_ratio`          | float   | Maximum share ratio until torrent is stopped from seeding/uploading
`max_seeding_time`   | integer | Maximum seeding time (seconds) until torrent is stopped from seeding
`name`               | string  | Torrent name
`num_complete`       | integer | Number of seeds in the swarm
`num_incomplete`     | integer | Number of leechers in the swarm
`num_leechs`         | integer | Number of leechers connected to
`num_seeds`          | integer | Number of seeds connected to
`priority`           | integer | Torrent priority. Returns -1 if queuing is disabled or torrent is in seed mode
`progress`           | float   | Torrent progress (percentage/100)
`ratio`              | float   | Torrent share ratio. Max ratio value: 9999.
`ratio_limit`        | float   | TODO (what is different from `max_ratio`?)
`save_path`          | string  | Path where this torrent's data is stored
`seeding_time`       | integer | Torrent elapsed time while complete (seconds)
`seeding_time_limit` | integer | TODO (what is different from `max_seeding_time`?) seeding_time_limit is a per torrent setting, when Automatic Torrent Management is disabled, furthermore then max_seeding_time is set to seeding_time_limit for this torrent. If Automatic Torrent Management is enabled, the value is -2. And if max_seeding_time is unset it have a default value -1.
`seen_complete`      | integer | Time (Unix Epoch) when this torrent was last seen complete
`seq_dl`             | bool    | True if sequential download is enabled
`size`               | integer | Total size (bytes) of files selected for download
`state`              | object  | state object see table below.
`super_seeding`      | bool    | True if super seeding is enabled
`tags`               | string  | Comma-concatenated tag list of the torrent
`time_active`        | integer | Total active time (seconds)
`total_size`         | integer | Total size (bytes) of all file in this torrent (including unselected ones)
`tracker`            | string  | The first tracker with working status. Returns empty string if no tracker is working.
`up_limit`           | integer | Torrent upload speed limit (bytes/s). `-1` if ulimited.
`uploaded`           | integer | Amount of data uploaded
`uploaded_session`   | integer | Amount of data uploaded this session
`upspeed`            | integer | Torrent upload speed (bytes/s)

Possible values of `state`:

Value         | Description
--------------|------------
`error`       | Some error occurred, applies to paused torrents
`missingFiles`| Torrent data files is missing
`uploading`   | Torrent is being seeded and data is being transferred
`pausedUP`    | Torrent is paused and has finished downloading
`queuedUP`    | Queuing is enabled and torrent is queued for upload
`stalledUP`   | Torrent is being seeded, but no connection were made
`checkingUP`  | Torrent has finished downloading and is being checked
`forcedUP`    | Torrent is forced to uploading and ignore queue limit
`allocating`  | Torrent is allocating disk space for download
`downloading` | Torrent is being downloaded and data is being transferred
`metaDL`      | Torrent has just started downloading and is fetching metadata
`pausedDL`    | Torrent is paused and has NOT finished downloading
`queuedDL`    | Queuing is enabled and torrent is queued for download
`stalledDL`   | Torrent is being downloaded, but no connection were made
`checkingDL`  | Same as checkingUP, but torrent has NOT finished downloading
`forcedDL`    | Torrent is forced to downloading to ignore queue limit
`checkingResumeData`| Checking resume data on qBt startup
`moving`      | Torrent is moving to another location
`unknown`     | Unknown status

Example:

```JSON
[
    {
        "dlspeed":9681262,
        "eta":87,
        "f_l_piece_prio":false,
        "force_start":false,
        "hash":"8c212779b4abde7c6bc608063a0d008b7e40ce32",
        "category":"",
        "tags": "",
        "name":"debian-8.1.0-amd64-CD-1.iso",
        "num_complete":-1,
        "num_incomplete":-1,
        "num_leechs":2,
        "num_seeds":54,
        "priority":1,
        "progress":0.16108787059783936,
        "ratio":0,
        "seq_dl":false,
        "size":657457152,
        "state":"downloading",
        "super_seeding":false,
        "upspeed":0
    },
    {
        another_torrent_info
    }
]
```

## Get torrent generic properties ##

Requires knowing the torrent hash. You can get it from [torrent list](#get-torrent-list).

Name: `properties`

**Parameters:**

Parameter | Type   | Description
----------|--------|------------
`hash`    | string | The hash of the torrent you want to get the generic properties of

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
404                               | Torrent hash was not found
200                               | All other scenarios- see JSON below

The response is a JSON of objects containing the following fields:

Property                  | Type    | Description
--------------------------|---------|------------
`save_path`               | string  | Torrent save path
`creation_date`           | integer | Torrent creation date (Unix timestamp)
`piece_size`              | integer | Torrent piece size (bytes)
`comment`                 | string  | Torrent comment
`total_wasted`            | integer | Total data wasted for torrent (bytes)
`total_uploaded`          | integer | Total data uploaded for torrent (bytes)
`total_uploaded_session`  | integer | Total data uploaded this session (bytes)
`total_downloaded`        | integer | Total data downloaded for torrent (bytes)
`total_downloaded_session`| integer | Total data downloaded this session (bytes)
`up_limit`                | integer | Torrent upload limit (bytes/s)
`dl_limit`                | integer | Torrent download limit (bytes/s)
`time_elapsed`            | integer | Torrent elapsed time (seconds)
`seeding_time`            | integer | Torrent elapsed time while complete (seconds)
`nb_connections`          | integer | Torrent connection count
`nb_connections_limit`    | integer | Torrent connection count limit
`share_ratio`             | float   | Torrent share ratio
`addition_date`           | integer | When this torrent was added (unix timestamp)
`completion_date`         | integer | Torrent completion date (unix timestamp)
`created_by`              | string  | Torrent creator
`dl_speed_avg`            | integer | Torrent average download speed (bytes/second)
`dl_speed`                | integer | Torrent download speed (bytes/second)
`eta`                     | integer | Torrent ETA (seconds)
`last_seen`               | integer | Last seen complete date (unix timestamp)
`peers`                   | integer | Number of peers connected to
`peers_total`             | integer | Number of peers in the swarm
`pieces_have`             | integer | Number of pieces owned
`pieces_num`              | integer | Number of pieces of the torrent
`reannounce`              | integer | Number of seconds until the next announce
`seeds`                   | integer | Number of seeds connected to
`seeds_total`             | integer | Number of seeds in the swarm
`total_size`              | integer | Torrent total size (bytes)
`up_speed_avg`            | integer | Torrent average upload speed (bytes/second)
`up_speed`                | integer | Torrent upload speed (bytes/second)

NB: `-1` is returned if the type of the property is integer but its value is not known.

Example:

```JSON
{
    "addition_date":1438429165,
    "comment":"\"Debian CD from cdimage.debian.org\"",
    "completion_date":1438429234,
    "created_by":"",
    "creation_date":1433605214,
    "dl_limit":-1,
    "dl_speed":0,
    "dl_speed_avg":9736015,
    "eta":8640000,
    "last_seen":1438430354,
    "nb_connections":3,
    "nb_connections_limit":250,
    "peers":1,
    "peers_total":89,
    "piece_size":524288,
    "pieces_have":1254,
    "pieces_num":1254,
    "reannounce":672,
    "save_path":"/Downloads/debian-8.1.0-amd64-CD-1.iso",
    "seeding_time":1128,
    "seeds":1,
    "seeds_total":254,
    "share_ratio":0.00072121022562178299,
    "time_elapsed":1197,
    "total_downloaded":681521119,
    "total_downloaded_session":681521119,
    "total_size":657457152,
    "total_uploaded":491520,
    "total_uploaded_session":491520,
    "total_wasted":23481724,
    "up_limit":-1,
    "up_speed":0,
    "up_speed_avg":410
}
```

## Get torrent trackers ##

Requires knowing the torrent hash. You can get it from [torrent list](#get-torrent-list).

Name: `trackers`

**Parameters:**

Parameter | Type   | Description
----------|--------|------------
`hash`    | string | The hash of the torrent you want to get the trackers of

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
404                               | Torrent hash was not found
200                               | All other scenarios- see JSON below

The response is a JSON array, where each element contains info about one tracker, with the following fields

Property         | Type     | Description
-----------------|----------|-------------
`url`            | string   | Tracker url
`status`         | integer  | Tracker status. See the table below for possible values
`tier`           | integer  | Tracker priority tier. Lower tier trackers are tried before higher tiers. Tier numbers are valid when `>= 0`, `< 0` is used as placeholder when `tier` does not exist for special entries (such as DHT).
`num_peers`      | integer  | Number of peers for current torrent, as reported by the tracker
`num_seeds`      | integer  | Number of seeds for current torrent, asreported by the tracker
`num_leeches`    | integer  | Number of leeches for current torrent, as reported by the tracker
`num_downloaded` | integer  | Number of completed downlods for current torrent, as reported by the tracker
`msg`            | string   | Tracker message (there is no way of knowing what this message is - it's up to tracker admins)

Possible values of `status`:

Value  | Description
-------|------------
0      | Tracker is disabled (used for DHT, PeX, and LSD)
1      | Tracker has not been contacted yet
2      | Tracker has been contacted and is working
3      | Tracker is updating
4      | Tracker has been contacted, but it is not working (or doesn't send proper replies)

Example:

```JSON
[
    {
        "msg":"",
        "num_peers":100,
        "status":2,
        "url":"http://bttracker.debian.org:6969/announce"
    },
    {
        another_tracker_info
    }
]
```

## Get torrent web seeds ##

Requires knowing the torrent hash. You can get it from [torrent list](#get-torrent-list).

Name: `webseeds`

**Parameters:**

Parameter | Type   | Description
----------|--------|------------
`hash`    | string | The hash of the torrent you want to get the webseeds of

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
404                               | Torrent hash was not found
200                               | All other scenarios- see JSON below

The response is a JSON array, where each element is information about one webseed, with the following fields

Property      | Type     | Description
--------------|----------|------------
`url`         | string   | URL of the web seed

Example:

```JSON
[
    {
        "url":"http://some_url/"
    },
    {
        "url":"http://some_other_url/"
    }
]
```

## Get torrent contents ##

Requires knowing the torrent hash. You can get it from [torrent list](#get-torrent-list).

Name: `files`

**Parameters:**

Parameter | Type   | Description
----------|--------|------------
`hash`    | string | The hash of the torrent you want to get the contents of
`indexes` _optional_ | string | The indexes of the files you want to retrieve. `indexes` can contain multiple values separated by a pipe.

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
404                               | Torrent hash was not found
200                               | All other scenarios- see JSON below

The response is a JSON array of objects containing the following fields:

Property       | Type          | Description
---------------|---------------|-------------
`index`        | integer       | File index
`name`         | string        | File name (including relative path)
`size`         | integer       | File size (bytes)
`progress`     | float         | File progress (percentage/100)
`priority`     | object       | priority object see table below. File priority. See possible values here below
`is_seed` _optional_ | bool          | True if file is seeding/complete
`piece_range`  | integer array | The first number is the starting piece index and the second number is the ending piece index (inclusive)
`availability` | float         | Percentage of file pieces currently available (percentage/100)

Possible values of `priority`:

Value      | Description
-----------|------------
`0`        | Do not download
`1`        | Normal priority
`4`        | Default Normal priority
`6`        | High priority
`7`        | Maximal priority

Example:

```JSON

[
    {
        "index":0,
        "is_seed":false,
        "name":"debian-8.1.0-amd64-CD-1.iso",
        "piece_range":[0,1253],
        "priority":1,
        "progress":0,
        "size":657457152,
        "availability":0.5,
    }
]
```

## Get torrent pieces' states ##

Requires knowing the torrent hash. You can get it from [torrent list](#get-torrent-list).

Name: `pieceStates`

**Parameters:**

Parameter | Type   | Description
----------|--------|------------
`hash`    | string | The hash of the torrent you want to get the pieces' states of

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
404                               | Torrent hash was not found
200                               | All other scenarios- see JSON below

The response is a JSON array of `return_objects`;

Possible values of `return_objects`:

Value      | Description
-----------|------------
`0`        | Not downloaded yet
`1`        | Now downloading
`2`        | Already downloaded

Example:

```JSON
[0,0,2,1,0,0,2,1]
```

## Get torrent pieces' hashes ##

Requires knowing the torrent hash. You can get it from [torrent list](#get-torrent-list).

Name: `pieceHashes`

**Parameters:**

Parameter | Type   | Description
----------|--------|------------
`hash`    | string | The hash of the torrent you want to get the pieces' hashes of

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
404                               | Torrent hash was not found
200                               | All other scenarios- see JSON below

The response is a JSON array of hashes (strings).

Example:

```JSON
["54eddd830a5b58480a6143d616a97e3a6c23c439","f8a99d225aa4241db100f88407fc3bdaead583ab","928fb615b9bd4dd8f9e9022552c8f8f37ef76f58"]
```

## Pause torrents ##

Requires knowing the torrent hashes. You can get it from [torrent list](#get-torrent-list).

Name: `pause`

**Parameters:**

Parameter   | Type     | Description
------------|----------|------------
`hashes`    | string   | The hashes of the torrents you want to pause. `hashes` can contain multiple hashes separated by a pipe, to pause multiple torrents, or set to `all`, to pause all torrents.

Example:

```http
/api/v2/torrents/pause?hashes=8c212779b4abde7c6bc608063a0d008b7e40ce32|54eddd830a5b58480a6143d616a97e3a6c23c439
```

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Resume torrents ##

Requires knowing the torrent hashes. You can get it from [torrent list](#get-torrent-list).

Name: `resume`

**Parameters:**

Parameter   | Type     | Description
------------|----------|------------
`hashes`    | string   | The hashes of the torrents you want to resume. `hashes` can contain multiple hashes separated by a pipe, to resume multiple torrents, or set to `all`, to resume all torrents.

Example:

```http
/api/v2/torrents/resume?hashes=8c212779b4abde7c6bc608063a0d008b7e40ce32|54eddd830a5b58480a6143d616a97e3a6c23c439
```

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Delete torrents ##

Requires knowing the torrent hashes. You can get it from [torrent list](#get-torrent-list).

Name: `delete`

**Parameters:**

Parameter   | Type     | Description
------------|----------|------------
`hashes`    | string   | The hashes of the torrents you want to delete. `hashes` can contain multiple hashes separated by a pipe, to delete multiple torrents, or set to `all`, to delete all torrents.
`deleteFiles` | bool | If set to `true`, the downloaded data will also be deleted, otherwise has no effect.

Example:

```http
/api/v2/torrents/delete?hashes=8c212779b4abde7c6bc608063a0d008b7e40ce32&deleteFiles=false
```

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Recheck torrents ##

Requires knowing the torrent hashes. You can get it from [torrent list](#get-torrent-list).

Name: `recheck`

**Parameters:**

Parameter   | Type     | Description
------------|----------|------------
`hashes`    | string   | The hashes of the torrents you want to recheck. `hashes` can contain multiple hashes separated by a pipe, to recheck multiple torrents, or set to `all`, to recheck all torrents.

Example:

```http
/api/v2/torrents/recheck?hashes=8c212779b4abde7c6bc608063a0d008b7e40ce32|54eddd830a5b58480a6143d616a97e3a6c23c439
```

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Reannounce torrents ##

Requires knowing the torrent hashes. You can get it from [torrent list](#get-torrent-list).

Name: `reannounce`

**Parameters:**

Parameter   | Type     | Description
------------|----------|------------
`hashes`    | string   | The hashes of the torrents you want to reannounce. `hashes` can contain multiple hashes separated by a pipe, to reannounce multiple torrents, or set to `all`, to reannounce all torrents.

Example:

```http
/api/v2/torrents/reannounce?hashes=8c212779b4abde7c6bc608063a0d008b7e40ce32|54eddd830a5b58480a6143d616a97e3a6c23c439
```

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Add new torrent ##

This method can add torrents from  server local file or from URLs. `http://`, `https://`, `magnet:` and `bc://bt/` links are supported.

Name: `add`

Add torrent from URLs example:

```http
POST /api/v2/torrents/add HTTP/1.1
User-Agent: Fiddler
Host: 127.0.0.1
Cookie: SID=your_sid
Content-Type: multipart/form-data; boundary=---------------------------6688794727912
Content-Length: length

-----------------------------6688794727912
Content-Disposition: form-data; name="urls"

https://torcache.net/torrent/3B1A1469C180F447B77021074DBBCCAEF62611E7.torrent
https://torcache.net/torrent/3B1A1469C180F447B77021074DBBCCAEF62611E8.torrent
-----------------------------6688794727912
Content-Disposition: form-data; name="savepath"

C:/Users/qBit/Downloads
-----------------------------6688794727912
Content-Disposition: form-data; name="cookie"

ui=28979218048197
-----------------------------6688794727912
Content-Disposition: form-data; name="category"

movies
-----------------------------6688794727912
Content-Disposition: form-data; name="skip_checking"

true
-----------------------------6688794727912
Content-Disposition: form-data; name="paused"

true
-----------------------------6688794727912
Content-Disposition: form-data; name="root_folder"

true
-----------------------------6688794727912--
```

Add torrents from files example:

```http
POST /api/v2/torrents/add HTTP/1.1
Content-Type: multipart/form-data; boundary=-------------------------acebdf13572468
User-Agent: Fiddler
Host: 127.0.0.1
Cookie: SID=your_sid
Content-Length: length

---------------------------acebdf13572468
Content-Disposition: form-data; name="torrents"; filename="8f18036b7a205c9347cb84a253975e12f7adddf2.torrent"
Content-Type: application/x-bittorrent

file_binary_data_goes_here
---------------------------acebdf13572468
Content-Disposition: form-data; name="torrents"; filename="UFS.torrent"
Content-Type: application/x-bittorrent

file_binary_data_goes_here
---------------------------acebdf13572468--

```

The above example will add two torrent files. `file_binary_data_goes_here` represents raw data of torrent file (basically a byte array).

**Parameters:**

Property                        | Type    | Description
--------------------------------|---------|------------
`urls`                          | string  | URLs separated with newlines
`torrents`                      | raw     | Raw data of torrent file. `torrents` can be presented multiple times.
`savepath` _optional_           | string  | Download folder
`cookie` _optional_             | string  | Cookie sent to download the .torrent file
`category` _optional_           | string  | Category for the torrent
`tags` _optional_               | string  | Tags for the torrent, split by ','
`skip_checking` _optional_      | string  | Skip hash checking. Possible values are `true`, `false` (default)
`paused` _optional_             | string  | Add torrents in the paused state. Possible values are `true`, `false` (default)
`root_folder` _optional_        | string  | Create the root folder. Possible values are `true`, `false`, unset (default)
`rename` _optional_             | string  | Rename torrent
`upLimit` _optional_            | integer | Set torrent upload speed limit. Unit in bytes/second
`dlLimit` _optional_            | integer | Set torrent download speed limit. Unit in bytes/second
`ratioLimit` _optional_         | float   | Set torrent share ratio limit
`seedingTimeLimit` _optional_   | integer | Set torrent seeding time limit. Unit in seconds
`autoTMM` _optional_            | bool    | Whether Automatic Torrent Management should be used
`sequentialDownload` _optional_ | string  | Enable sequential download. Possible values are `true`, `false` (default)
`firstLastPiecePrio` _optional_ | string  | Prioritize download first last piece. Possible values are `true`, `false` (default)

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
415                               | Torrent file is not valid
200                               | All other scenarios

## Add trackers to torrent ##

Requires knowing the torrent hash. You can get it from [torrent list](#get-torrent-list).

Name: `addTrackers`

**Parameters:**

Property                        | Type    | Description
--------------------------------|---------|------------
`hash`                          | string  | Torrent file to add trackers to
`urls`                          | string  | URLs separated with newlines


```http
POST /api/v2/torrents/addTrackers HTTP/1.1
User-Agent: Fiddler
Host: 127.0.0.1
Cookie: SID=your_sid
Content-Type: application/x-www-form-urlencoded
Content-Length: length

hash=8c212779b4abde7c6bc608063a0d008b7e40ce32&urls=http://192.168.0.1/announce%0Audp://192.168.0.1:3333/dummyAnnounce
```

This adds two trackers to torrent with hash `8c212779b4abde7c6bc608063a0d008b7e40ce32`. Note `%0A` (aka LF newline) between trackers. Ampersand in tracker urls **MUST** be escaped.

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
404                               | Torrent hash was not found
200                               | All other scenarios

## Edit trackers ##

Name: `editTracker`

**Parameters:**

Parameter                         | Type    | Description
----------------------------------|---------|------------
`hash`                            | string  | The hash of the torrent
`origUrl`                         | string  | The tracker URL you want to edit
`newUrl`                          | string  | The new URL to replace the `origUrl`

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
400                               | `newUrl` is not a valid URL
404                               | Torrent hash was not found
409                               | `newUrl` already exists for the torrent
409                               | `origUrl` was not found
200                               | All other scenarios

## Remove trackers ##

Name: `removeTrackers`

**Parameters:**

Parameter                         | Type    | Description
----------------------------------|---------|------------
`hash`                            | string  | The hash of the torrent
`urls`                            | string  | URLs to remove, separated by a pipe

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
404                               | Torrent hash was not found
409                               | All `urls` were not found
200                               | All other scenarios

## Add peers ##

Name: `addPeers`

**Parameters:**

Parameter                         | Type    | Description
----------------------------------|---------|------------
`hashes`                          | string  | The hash of the torrent, or multiple hashes separated by a pipe
`peers`                           | string  | The peer to add, or multiple peers separated by a pipe. Each peer is a colon-separated `host:port`

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
400                               | None of the supplied peers are valid
200                               | All other scenarios

## Increase torrent priority ##

Requires knowing the torrent hash. You can get it from [torrent list](#get-torrent-list).

Name: `increasePrio`

**Parameters:**

Parameter   | Type     | Description
------------|----------|------------
`hashes`    | string   | The hashes of the torrents you want to increase the priority of. `hashes` can contain multiple hashes separated by a pipe, to increase the priority of multiple torrents, or set to `all`, to increase the priority of all torrents.

Example:

```http
/api/v2/torrents/increasePrio?hashes=8c212779b4abde7c6bc608063a0d008b7e40ce32|54eddd830a5b58480a6143d616a97e3a6c23c439
```

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
409                               | Torrent queueing is not enabled
200                               | All other scenarios

## Decrease torrent priority ##

Requires knowing the torrent hash. You can get it from [torrent list](#get-torrent-list).

Name: `decreasePrio`

**Parameters:**

Parameter   | Type     | Description
------------|----------|------------
`hashes`    | string   | The hashes of the torrents you want to decrease the priority of. `hashes` can contain multiple hashes separated by a pipe, to decrease the priority of multiple torrents, or set to `all`, to decrease the priority of all torrents.

Example:

```http
/api/v2/torrents/decreasePrio?hashes=8c212779b4abde7c6bc608063a0d008b7e40ce32|54eddd830a5b58480a6143d616a97e3a6c23c439
```

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
409                               | Torrent queueing is not enabled
200                               | All other scenarios

## Maximal torrent priority ##

Requires knowing the torrent hash. You can get it from [torrent list](#get-torrent-list).

Name: `topPrio`

**Parameters:**

Parameter   | Type     | Description
------------|----------|------------
`hashes`    | string   | The hashes of the torrents you want to set to the maximum priority. `hashes` can contain multiple hashes separated by a pipe, to set multiple torrents to the maximum priority, or set to `all`, to set all torrents to the maximum priority.

Example:

```http
/api/v2/torrents/topPrio?hashes=8c212779b4abde7c6bc608063a0d008b7e40ce32|54eddd830a5b58480a6143d616a97e3a6c23c439
```

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
409                               | Torrent queueing is not enabled
200                               | All other scenarios

## Minimal torrent priority ##

Requires knowing the torrent hash. You can get it from [torrent list](#get-torrent-list).

Name: `bottomPrio`

**Parameters:**

Parameter   | Type     | Description
------------|----------|------------
`hashes`    | string   | The hashes of the torrents you want to set to the minimum priority. `hashes` can contain multiple hashes separated by a pipe, to set multiple torrents to the minimum priority, or set to `all`, to set all torrents to the minimum priority.

Example:

```http
/api/v2/torrents/bottomPrio?hashes=8c212779b4abde7c6bc608063a0d008b7e40ce32|54eddd830a5b58480a6143d616a97e3a6c23c439
```

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
409                               | Torrent queueing is not enabled
200                               | All other scenarios

## Set file priority ##

Name: `filePrio`

**Parameters:**

Parameter                         | Type    | Description
----------------------------------|---------|------------
`hash`                            | string  | The hash of the torrent
`id`                              | string  | File ids, separated by a pipe
`priority`                        | object  | priority object see table below. File priority to set (consult [torrent contents API](#get-torrent-contents) for possible values)

`id` values correspond to file position inside the array returned by [torrent contents API](#get-torrent-contents), e.g. `id=0` for first file, `id=1` for second file, etc.

Since 2.8.2 it is reccomended to use `index` field returned by [torrent contents API](#get-torrent-contents) (since the files can be filtered and the `index` value may differ from the position inside the response array).

Possible values of `priority`:

Value      | Description
-----------|------------
`0`        | Do not download
`4`        | Normal priority
`6`        | High priority
`7`        | Maximal priority

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
400                               | Priority is invalid
400                               | At least one file `id` is not a valid integer
404                               | Torrent hash was not found
409                               | Torrent metadata hasn't downloaded yet
409                               | At least one file `id` was not found
200                               | All other scenarios

## Get torrent download limit ##

Requires knowing the torrent hash. You can get it from [torrent list](#get-torrent-list).

Name: `downloadLimit`

```http
POST /api/v2/torrents/downloadLimit HTTP/1.1
User-Agent: Fiddler
Host: 127.0.0.1
Cookie: SID=your_sid
Content-Type: application/x-www-form-urlencoded
Content-Length: length

hashes=8c212779b4abde7c6bc608063a0d008b7e40ce32|284b83c9c7935002391129fd97f43db5d7cc2ba0
```

`hashes` can contain multiple hashes separated by `|` or set to `all`

Server reply (example):

```http
HTTP/1.1 200 OK
content-type: application/json
content-length: length

{"8c212779b4abde7c6bc608063a0d008b7e40ce32":338944,"284b83c9c7935002391129fd97f43db5d7cc2ba0":123}
```

`8c212779b4abde7c6bc608063a0d008b7e40ce32` is the hash of the torrent and `338944` its download speed limit in bytes per second; this value will be zero if no limit is applied.

## Set torrent download limit ##

Requires knowing the torrent hash. You can get it from [torrent list](#get-torrent-list).

```http
POST /api/v2/torrents/setDownloadLimit HTTP/1.1
User-Agent: Fiddler
Host: 127.0.0.1
Cookie: SID=your_sid
Content-Type: application/x-www-form-urlencoded
Content-Length: length

hashes=8c212779b4abde7c6bc608063a0d008b7e40ce32|284b83c9c7935002391129fd97f43db5d7cc2ba0&limit=131072
```

`hashes` can contain multiple hashes separated by `|` or set to `all`
`limit` is the download speed limit in bytes per second you want to set.

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Set torrent share limit ##

Requires knowing the torrent hash. You can get it from [torrent list](#get-torrent-list).

Name: `setShareLimits`

```http
POST /api/v2/torrents/setShareLimits HTTP/1.1
User-Agent: Fiddler
Host: 127.0.0.1
Cookie: SID=your_sid
Content-Type: application/x-www-form-urlencoded
Content-Length: length

hashes=8c212779b4abde7c6bc608063a0d008b7e40ce32|284b83c9c7935002391129fd97f43db5d7cc2ba0&ratioLimit=1.0&seedingTimeLimit=60
```

`hashes` can contain multiple hashes separated by `|` or set to `all`
`ratioLimit` is the max ratio the torrent should be seeded until. `-2` means the global limit should be used, `-1` means no limit.
`seedingTimeLimit` is the max amount of time the torrent should be seeded. `-2` means the global limit should be used, `-1` means no limit.

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Get torrent upload limit ##

Requires knowing the torrent hash. You can get it from [torrent list](#get-torrent-list).

Name: `uploadLimit`

```http
POST /api/v2/torrents/uploadLimit HTTP/1.1
User-Agent: Fiddler
Host: 127.0.0.1
Cookie: SID=your_sid
Content-Type: application/x-www-form-urlencoded
Content-Length: length

hashes=8c212779b4abde7c6bc608063a0d008b7e40ce32|284b83c9c7935002391129fd97f43db5d7cc2ba0
```

`hashes` can contain multiple hashes separated by `|` or set to `all`

Server reply (example):

```http
HTTP/1.1 200 OK
content-type: application/json
content-length: length

{"8c212779b4abde7c6bc608063a0d008b7e40ce32":338944,"284b83c9c7935002391129fd97f43db5d7cc2ba0":123}
```

`8c212779b4abde7c6bc608063a0d008b7e40ce32` is the hash of the torrent in the request and `338944` its upload speed limit in bytes per second; this value will be zero if no limit is applied.

## Set torrent upload limit ##

Requires knowing the torrent hash. You can get it from [torrent list](#get-torrent-list).

Name: `setUploadLimit`

```http
POST /api/v2/torrents/setUploadLimit HTTP/1.1
User-Agent: Fiddler
Host: 127.0.0.1
Cookie: SID=your_sid
Content-Type: application/x-www-form-urlencoded
Content-Length: length

hashes=8c212779b4abde7c6bc608063a0d008b7e40ce32|284b83c9c7935002391129fd97f43db5d7cc2ba0&limit=131072
```

`hashes` can contain multiple hashes separated by `|` or set to `all`
`limit` is the upload speed limit in bytes per second you want to set.

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Set torrent location ##

Requires knowing the torrent hash. You can get it from [torrent list](#get-torrent-list).

Name: `setLocation`

```http
POST /api/v2/torrents/setLocation HTTP/1.1
User-Agent: Fiddler
Host: 127.0.0.1
Cookie: SID=your_sid
Content-Type: application/x-www-form-urlencoded
Content-Length: length

hashes=8c212779b4abde7c6bc608063a0d008b7e40ce32|284b83c9c7935002391129fd97f43db5d7cc2ba0&location=/mnt/nfs/media
```

`hashes` can contain multiple hashes separated by `|` or set to `all`
`location` is the location to download the torrent to. If the location doesn't exist, the torrent's location is unchanged.

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
400                               | Save path is empty
403                               | User does not have write access to directory
409                               | Unable to create save path directory
200                               | All other scenarios

## Set torrent name ##

Requires knowing the torrent hash. You can get it from [torrent list](#get-torrent-list).

Name: `rename`

```http
POST /api/v2/torrents/rename HTTP/1.1
User-Agent: Fiddler
Host: 127.0.0.1
Cookie: SID=your_sid
Content-Type: application/x-www-form-urlencoded
Content-Length: length

hash=8c212779b4abde7c6bc608063a0d008b7e40ce32&name=This%20is%20a%20test
```

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
404                               | Torrent hash is invalid
409                               | Torrent name is empty
200                               | All other scenarios

## Set torrent category ##

Requires knowing the torrent hash. You can get it from [torrent list](#get-torrent-list).

Name: `setCategory`

```http
POST /api/v2/torrents/setCategory HTTP/1.1
User-Agent: Fiddler
Host: 127.0.0.1
Cookie: SID=your_sid
Content-Type: application/x-www-form-urlencoded
Content-Length: length

hashes=8c212779b4abde7c6bc608063a0d008b7e40ce32|284b83c9c7935002391129fd97f43db5d7cc2ba0&category=CategoryName
```

`hashes` can contain multiple hashes separated by `|` or set to `all`

`category` is the torrent category you want to set.

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
409                               | Category name does not exist
200                               | All other scenarios

## Get all categories ##

Name: `categories`

Parameters:

None

Returns all categories in JSON format, e.g.:

```JSON
{
    "Video": {
        "name": "Video",
        "savePath": "/home/user/torrents/video/"
    },
    "eBooks": {
        "name": "eBooks",
        "savePath": "/home/user/torrents/eBooks/"
    }
}
```
**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Add new category ##

Name: `createCategory`

```http
POST /api/v2/torrents/createCategory HTTP/1.1
User-Agent: Fiddler
Host: 127.0.0.1
Cookie: SID=your_sid
Content-Type: application/x-www-form-urlencoded
Content-Length: length

category=CategoryName&savePath=/path/to/dir
```

`category` is the category you want to create.

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
400                               | Category name is empty
409                               | Category name is invalid
200                               | All other scenarios

## Edit category ##

Name: `editCategory`

```http
POST /api/v2/torrents/editCategory HTTP/1.1
User-Agent: Fiddler
Host: 127.0.0.1
Cookie: SID=your_sid
Content-Type: application/x-www-form-urlencoded
Content-Length: length

category=CategoryName&savePath=/path/to/save/torrents/to
```

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
400                               | Category name is empty
409                               | Category editing failed
200                               | All other scenarios

## Remove categories ##

Name: `removeCategories`

```http
POST /api/v2/torrents/removeCategories HTTP/1.1
User-Agent: Fiddler
Host: 127.0.0.1
Cookie: SID=your_sid
Content-Type: application/x-www-form-urlencoded
Content-Length: length

categories=Category1%0ACategory2
```

`categories` can contain multiple cateogies separated by `\n` (%0A urlencoded)

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Add torrent tags ##

Requires knowing the torrent hash. You can get it from [torrent list](#get-torrent-list).

Name: `addTags`

```http
POST /api/v2/torrents/addTags HTTP/1.1
User-Agent: Fiddler
Host: 127.0.0.1
Cookie: SID=your_sid
Content-Type: application/x-www-form-urlencoded
Content-Length: length

hashes=8c212779b4abde7c6bc608063a0d008b7e40ce32|284b83c9c7935002391129fd97f43db5d7cc2ba0&tags=TagName1,TagName2
```

`hashes` can contain multiple hashes separated by `|` or set to `all`

`tags` is the list of tags you want to add to passed torrents.

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Remove torrent tags ##

Requires knowing the torrent hash. You can get it from [torrent list](#get-torrent-list).

Name: `removeTags`

```http
POST /api/v2/torrents/removeTags HTTP/1.1
User-Agent: Fiddler
Host: 127.0.0.1
Cookie: SID=your_sid
Content-Type: application/x-www-form-urlencoded
Content-Length: length

hashes=8c212779b4abde7c6bc608063a0d008b7e40ce32|284b83c9c7935002391129fd97f43db5d7cc2ba0&tags=TagName1,TagName2
```

`hashes` can contain multiple hashes separated by `|` or set to `all`

`tags` is the list of tags you want to remove from passed torrents.
Empty list removes all tags from relevant torrents.

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Get all tags ##

Name: `tags`

Parameters:

None

Returns all tags in JSON format, e.g.:

```JSON
[
    "Tag 1",
    "Tag 2"
]
```
**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Create tags ##

Name: `createTags`

```http
POST /api/v2/torrents/createTags HTTP/1.1
User-Agent: Fiddler
Host: 127.0.0.1
Cookie: SID=your_sid
Content-Type: application/x-www-form-urlencoded
Content-Length: length

tags=TagName1,TagName2
```
`tags` is a list of tags you want to create.
Can contain multiple tags separated by `,`.

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Delete tags ##

Name: `deleteTags`

```http
POST /api/v2/torrents/deleteTags HTTP/1.1
User-Agent: Fiddler
Host: 127.0.0.1
Cookie: SID=your_sid
Content-Type: application/x-www-form-urlencoded
Content-Length: length

tags=TagName1,TagName2
```

`tags` is a list of tags you want to delete.
Can contain multiple tags separated by `,`.

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Set automatic torrent management ##

Requires knowing the torrent hash. You can get it from [torrent list](#get-torrent-list).

Name: `setAutoManagement`

```http
POST /api/v2/torrents/setAutoManagement HTTP/1.1
User-Agent: Fiddler
Host: 127.0.0.1
Cookie: SID=your_sid
Content-Type: application/x-www-form-urlencoded
Content-Length: length

hashes=8c212779b4abde7c6bc608063a0d008b7e40ce32|284b83c9c7935002391129fd97f43db5d7cc2ba0&enable=true
```

`hashes` can contain multiple hashes separated by `|` or set to `all`
`enable` is a boolean, affects the torrents listed in `hashes`, default is `false`

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Toggle sequential download ##

Requires knowing the torrent hash. You can get it from [torrent list](#get-torrent-list).

Name: `toggleSequentialDownload`

**Parameters:**

Parameter   | Type     | Description
------------|----------|------------
`hashes`    | string   | The hashes of the torrents you want to toggle sequential download for. `hashes` can contain multiple hashes separated by a pipe, to toggle sequential download for multiple torrents, or set to `all`, to toggle sequential download for all torrents.

Example:

```http
/api/v2/torrents/toggleSequentialDownload?hashes=8c212779b4abde7c6bc608063a0d008b7e40ce32|54eddd830a5b58480a6143d616a97e3a6c23c439
```

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Set first/last piece priority ##

Requires knowing the torrent hash. You can get it from [torrent list](#get-torrent-list).

Name: `toggleFirstLastPiecePrio`

**Parameters:**

Parameter   | Type     | Description
------------|----------|------------
`hashes`    | string   | The hashes of the torrents you want to toggle the first/last piece priority for. `hashes` can contain multiple hashes separated by a pipe, to toggle the first/last piece priority for multiple torrents, or set to `all`, to toggle the first/last piece priority for all torrents.

Example:

```http
/api/v2/torrents/toggleFirstLastPiecePrio?hashes=8c212779b4abde7c6bc608063a0d008b7e40ce32|54eddd830a5b58480a6143d616a97e3a6c23c439
```

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Set force start ##

Requires knowing the torrent hash. You can get it from [torrent list](#get-torrent-list).

Name: `setForceStart`

```http
POST /api/v2/torrents/setForceStart HTTP/1.1
User-Agent: Fiddler
Host: 127.0.0.1
Cookie: SID=your_sid
Content-Type: application/x-www-form-urlencoded
Content-Length: length

hashes=8c212779b4abde7c6bc608063a0d008b7e40ce32?value=true
```

`hashes` can contain multiple hashes separated by `|` or set to `all`
`value` is a boolean, affects the torrents listed in `hashes`, default is `false`

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Set super seeding ##

Requires knowing the torrent hash. You can get it from [torrent list](#get-torrent-list).

Name: `setSuperSeeding`

```http
POST /api/v2/torrents/setSuperSeeding HTTP/1.1
User-Agent: Fiddler
Host: 127.0.0.1
Cookie: SID=your_sid
Content-Type: application/x-www-form-urlencoded
Content-Length: length

hashes=8c212779b4abde7c6bc608063a0d008b7e40ce32?value=true
```

`hashes` can contain multiple hashes separated by `|` or set to `all`
`value` is a boolean, affects the torrents listed in `hashes`, default is `false`

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Rename file ##

Name: `renameFile`

**Parameters:**

Parameter                         | Type     | Description
----------------------------------|----------|------------
`hash`                            | string   | The hash of the torrent
`oldPath`                         | string   | The old path of the torrent
`newPath`                         | string   | The new path to use for the file

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
400                               | Missing `newPath` parameter
409                               | Invalid `newPath` or `oldPath`, or `newPath` already in use
200                               | All other scenarios

## Rename folder ##

Name: `renameFolder`

**Parameters:**

Parameter                         | Type     | Description
----------------------------------|----------|------------
`hash`                            | string   | The hash of the torrent
`oldPath`                         | string   | The old path of the torrent
`newPath`                         | string   | The new path to use for the file

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
400                               | Missing `newPath` parameter
409                               | Invalid `newPath` or `oldPath`, or `newPath` already in use
200                               | All other scenarios

# RSS (experimental) #

All RSS API methods are under "rss", e.g.: `/api/v2/rss/methodName`.

## Add folder ##

Name: `addFolder`

Parameters:

Parameter                         | Type    | Description
----------------------------------|---------|------------
`path`                            | string  | Full path of added folder (e.g. "The Pirate Bay\Top100")

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
409                               | Failure to add folder
200                               | All other scenarios

## Add feed ##

Name: `addFeed`

Parameters:

Parameter                         | Type    | Description
----------------------------------|---------|------------
`url`                             | string  | URL of RSS feed (e.g. "[http://thepiratebay.org/rss//top100/200](http://thepiratebay.org/rss//top100/200)")
`path` _optional_                 | string  | Full path of added folder (e.g. "The Pirate Bay\Top100\Video")

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
409                               | Failure to add feed
200                               | All other scenarios

## Remove item ##

Removes folder or feed.

Name: `removeItem`

Parameters:

Parameter                         | Type    | Description
----------------------------------|---------|------------
`path`                            | string  | Full path of removed item (e.g. "The Pirate Bay\Top100")

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
409                               | Failure to remove item
200                               | All other scenarios

## Move item ##

Moves/renames folder or feed.

Name: `moveItem`

Parameters:

Parameter                         | Type    | Description
----------------------------------|---------|------------
`itemPath`                        | string  | Current full path of item (e.g. "The Pirate Bay\Top100")
`destPath`                        | string  | New full path of item (e.g. "The Pirate Bay")

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
409                               | Failure to move item
200                               | All other scenarios

## Get all items ##

Name: `items`

Parameters:

Parameter                         | Type    | Description
----------------------------------|---------|------------
`withData` _optional_             | bool    | True if you need current feed articles

Returns all RSS items in JSON format, e.g.:

```JSON
{
    "HD-Torrents.org": "https://hd-torrents.org/rss.php",
    "PowerfulJRE": "https://www.youtube.com/feeds/videos.xml?channel_id=UCzQUP1qoWDoEbmsQxvdjxgQ",
    "The Pirate Bay": {
        "Audio": "https://thepiratebay.org/rss//top100/100",
        "Video": "https://thepiratebay.org/rss//top100/200"
    }
}
```

## Mark as read ##

If `articleId` is provided only the article is marked as read otherwise the whole feed is going to be marked as read.

Name: `markAsRead`

Parameters:

Parameter                         | Type    | Description
----------------------------------|---------|------------
`itemPath`                        | string  | Current full path of item (e.g. "The Pirate Bay\Top100")
`articleId` _optional_            | string  | ID of article

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Refresh item ##

Refreshes folder or feed.

Name: `refreshItem`

Parameters:

Parameter                         | Type    | Description
----------------------------------|---------|------------
`itemPath`                        | string  | Current full path of item (e.g. "The Pirate Bay\Top100")

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Set auto-downloading rule ##

Name: `setRule`

Parameters:

Parameter                         | Type    | Description
----------------------------------|---------|------------
`ruleName`                        | string  | Rule name (e.g. "Punisher")
`ruleDef`                         | string  | JSON encoded rule definition

Rule definition is JSON encoded dictionary with the following fields:

Field                             | Type    | Description
----------------------------------|---------|------------
`enabled`                         | bool    | Whether the rule is enabled
`mustContain`                     | string  | The substring that the torrent name must contain
`mustNotContain`                  | string  | The substring that the torrent name must not contain
`useRegex`                        | bool    | Enable regex mode in "mustContain" and "mustNotContain"
`episodeFilter`                   | string  | Episode filter definition
`smartFilter`                     | bool    | Enable smart episode filter
`previouslyMatchedEpisodes`       | list    | The list of episode IDs already matched by smart filter
`affectedFeeds`                   | list    | The feed URLs the rule applied to
`ignoreDays`                      | number  | Ignore sunsequent rule matches
`lastMatch`                       | string  | The rule last match time
`addPaused`                       | bool    | Add matched torrent in paused mode
`assignedCategory`                | string  | Assign category to the torrent
`savePath`                        | string  | Save torrent to the given directory

E.g.:

```JSON
{
    "enabled": false,
    "mustContain": "The *Punisher*",
    "mustNotContain": "",
    "useRegex": false,
    "episodeFilter": "1x01-;",
    "smartFilter": false,
    "previouslyMatchedEpisodes": [
    ],
    "affectedFeeds": [
        "http://showrss.info/user/134567.rss?magnets=true"
    ],
    "ignoreDays": 0,
    "lastMatch": "20 Nov 2017 09:05:11",
    "addPaused": true,
    "assignedCategory": "",
    "savePath": "C:/Users/JohnDoe/Downloads/Punisher"
}
```

## Rename auto-downloading rule ##

Name: `renameRule`

Parameters:

Parameter                         | Type    | Description
----------------------------------|---------|------------
`ruleName`                        | string  | Rule name (e.g. "Punisher")
`newRuleName`                     | string  | New rule name (e.g. "The Punisher")

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Remove auto-downloading rule ##

Name: `removeRule`

Parameters:

Parameter                         | Type    | Description
----------------------------------|---------|------------
`ruleName`                        | string  | Rule name (e.g. "Punisher")

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios


## Get all auto-downloading rules ##

Name: `rules`

Returns all auto-downloading rules in JSON format, e.g.:

```JSON
{
    "The Punisher": {
        "enabled": false,
        "mustContain": "The *Punisher*",
        "mustNotContain": "",
        "useRegex": false,
        "episodeFilter": "1x01-;",
        "smartFilter": false,
        "previouslyMatchedEpisodes": [
        ],
        "affectedFeeds": [
            "http://showrss.info/user/134567.rss?magnets=true"
        ],
        "ignoreDays": 0,
        "lastMatch": "20 Nov 2017 09:05:11",
        "addPaused": true,
        "assignedCategory": "",
        "savePath": "C:/Users/JohnDoe/Downloads/Punisher"
    }
}
```
**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Get all articles matching a rule ##

Name: `matchingArticles`

Parameter                         | Type    | Description
----------------------------------|---------|------------
`ruleName`                        | string  | Rule name (e.g. "Linux")


Returns all articles that match a rule by feed name in JSON format, e.g.:

```JSON
{
    "DistroWatch":[
        "sparkylinux-5.11-i686-minimalgui.iso.torrent",
        "sparkylinux-5.11-x86_64-minimalgui.iso.torrent",
        "sparkylinux-5.11-i686-xfce.iso.torrent",
        "bluestar-linux-5.6.3-2020.04.09-x86_64.iso.torrent",
        "robolinux64-mate3d-v10.10.iso.torrent",
    ],
    "Linuxtracker":[
        "[Alpine Linux] alpine-extended-3.11.6",
        "[Alpine Linux] alpine-standard-3.11.6",
        "[Linuxfx] linuxfx10-wxs-lts-beta5.iso",
        "[Linux Lite] linux-lite-5.0-rc1-64bit.iso (MULTI)",
        "[Scientific Linux] SL-7.8-x86_64-Pack",
        "[NixOS] nixos-plasma5-20.03.1418.5272327b81e-x86_64-linux.iso"
    ]
}
```

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios


# Search #

All Search API methods are under "search", e.g.: `/api/v2/search/methodName`.

## Start search ##

Name: `start`

**Parameters:**

Parameter                         | Type    | Description
----------------------------------|---------|------------
`pattern`                         | string  | Pattern to search for (e.g. "Ubuntu 18.04")
`plugins`                         | string  | Plugins to use for searching (e.g. "legittorrents"). Supports multiple plugins separated by a pipe. Also supports `all` and `enabled`
`category`                        | string  | Categories to limit your search to (e.g. "legittorrents"). Available categories depend on the specified `plugins`. Also supports `all`

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
409                               | User has reached the limit of max `Running` searches (currently set to 5)
200                               | All other scenarios- see JSON below

The response is a JSON object with the following fields

Field                             | Type    | Description
----------------------------------|---------|------------
`id`                              | number  | ID of the search job

Example:

```JSON
{
    "id": 12345
}
```

## Stop search ##

Name: `stop`

**Parameters:**

Parameter                         | Type    | Description
----------------------------------|---------|------------
`id`                              | number  | ID of the search job

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
404                               | Search job was not found
200                               | All other scenarios

## Get search status ##

Name: `status`

**Parameters:**

Parameter                         | Type    | Description
----------------------------------|---------|------------
`id` _optional_                   | number  | ID of the search job. If not specified, all search jobs are returned

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
404                               | Search job was not found
200                               | All other scenarios- see JSON below

The response is a JSON array of objects containing the following fields

Field                             | Type    | Description
----------------------------------|---------|------------
`id`                              | number  | ID of the search job
`status`                          | string  | Current status of the search job (either `Running` or `Stopped`)
`total`                           | number  | Total number of results. If the status is `Running` this number may contineu to increase

Example:

```JSON
[
    {
        "id": 12345,
        "status": "Running",
        "total": 170
    }
]
```

## Get search results ##

Name: `results`

**Parameters:**

Parameter                         | Type    | Description
----------------------------------|---------|------------
`id`                              | number  | ID of the search job
`limit` _optional_                | number  | max number of results to return. 0 or negative means no limit
`offset` _optional_               | number  | result to start at. A negative number means count backwards (e.g. `-2` returns the 2 most recent results)

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
404                               | Search job was not found
409                               | Offset is too large, or too small (e.g. absolute value of negative number is greater than # results)
200                               | All other scenarios- see JSON below

The response is a JSON object with the following fields

Field                             | Type    | Description
----------------------------------|---------|------------
`results`                         | array   | Array of `result` objects- see table below
`status`                          | string  | Current status of the search job (either `Running` or `Stopped`)
`total`                           | number  | Total number of results. If the status is `Running` this number may continue to increase

**Result object:**

Field                             | Type    | Description
----------------------------------|---------|------------
`descrLink`                       | string  | URL of the torrent's description page
`fileName`                        | string  | Name of the file
`fileSize`                        | number  | Size of the file in Bytes
`fileUrl`                         | string  | Torrent download link (usually either .torrent file or magnet link)
`nbLeechers`                      | number  | Number of leechers
`nbSeeders`                       | number  | Number of seeders
`siteUrl`                         | string  | URL of the torrent site

Example:

```JSON
{
    "results": [
        {
            "descrLink": "http://www.legittorrents.info/index.php?page=torrent-details&id=8d5f512e1acb687029b8d7cc6c5a84dce51d7a41",
            "fileName": "Ubuntu-10.04-32bit-NeTV.ova",
            "fileSize": -1,
            "fileUrl": "http://www.legittorrents.info/download.php?id=8d5f512e1acb687029b8d7cc6c5a84dce51d7a41&f=Ubuntu-10.04-32bit-NeTV.ova.torrent",
            "nbLeechers": 1,
            "nbSeeders": 0,
            "siteUrl": "http://www.legittorrents.info"
        },
        {
            "descrLink": "http://www.legittorrents.info/index.php?page=torrent-details&id=d5179f53e105dc2c2401bcfaa0c2c4936a6aa475",
            "fileName": "mangOH-Legato-17_06-Ubuntu-16_04.ova",
            "fileSize": -1,
            "fileUrl": "http://www.legittorrents.info/download.php?id=d5179f53e105dc2c2401bcfaa0c2c4936a6aa475&f=mangOH-Legato-17_06-Ubuntu-16_04.ova.torrent",
            "nbLeechers": 0,
            "nbSeeders": 59,
            "siteUrl": "http://www.legittorrents.info"
        }
    ],
    "status": "Running",
    "total": 2
}
```

## Delete search ##

Name: `delete`

**Parameters:**

Parameter                         | Type    | Description
----------------------------------|---------|------------
`id`                              | number  | ID of the search job

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
404                               | Search job was not found
200                               | All other scenarios

## Get search plugins ##

Name: `plugins`

**Parameters:**

None

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios- see JSON below

The response is a JSON array of objects containing the following fields

Field                             | Type    | Description
----------------------------------|---------|------------
`enabled`                         | bool    | Whether the plugin is enabled
`fullName`                        | string  | Full name of the plugin
`name`                            | string  | Short name of the plugin
`supportedCategories`             | array   | List of category objects
`url`                             | string  | URL of the torrent site
`version`                         | string  | Installed version of the plugin

```JSON
[
    {
        "enabled": true,
        "fullName": "Legit Torrents",
        "name": "legittorrents",
        "supportedCategories": [{
            "id": "all",
            "name": "All categories"
        }, {
            "id": "anime",
            "name": "Anime"
        }, {
            "id": "books",
            "name": "Books"
        }, {
            "id": "games",
            "name": "Games"
        }, {
            "id": "movies",
            "name": "Movies"
        }, {
            "id": "music",
            "name": "Music"
        }, {
            "id": "tv",
            "name": "TV shows"
        }],
        "url": "http://www.legittorrents.info",
        "version": "2.3"
    }
]
```

**Category object:**

Field                      | Type    | Description
---------------------------|---------|------------
`id`                       | string  | Id
`name`                     | string  | Name

## Install search plugin ##

Name: `installPlugin`

**Parameters:**

Parameter                         | Type    | Description
----------------------------------|---------|------------
`sources`                         | string  | Url or file path of the plugin to install (e.g. "[https://raw.githubusercontent.com/qbittorrent/search-plugins/master/nova3/engines/legittorrents.py](https://raw.githubusercontent.com/qbittorrent/search-plugins/master/nova3/engines/legittorrents.py)"). Supports multiple sources separated by a pipe

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Uninstall search plugin ##

Name: `uninstallPlugin`

**Parameters:**

Parameter                         | Type    | Description
----------------------------------|---------|------------
`names`                           | string  | Name of the plugin to uninstall (e.g. "legittorrents"). Supports multiple names separated by a pipe

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Enable search plugin ##

Name: `enablePlugin`

**Parameters:**

Parameter                         | Type    | Description
----------------------------------|---------|------------
`names`                           | string  | Name of the plugin to enable/disable (e.g. "legittorrents"). Supports multiple names separated by a pipe
`enable`                          | bool    | Whether the plugins should be enabled

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

## Update search plugins ##

Name: `updatePlugins`

**Parameters:**

None

**Returns:**

HTTP Status Code                  | Scenario
----------------------------------|---------------------
200                               | All scenarios

# WebAPI versioning #
WebAPI uses the following versioning: `1.2.3`:
1. Main version. Should be changed only on some global changes (e.g. total redesign/relayout)
2. Changed on incompatible API changes (i.e. if it breaks outdated clients). E.g. if you change/remove something
3. Changed on compatible API changes (i.e. if it doesn't break outdated clients). E.g. if you add something new outdated clients still can access old subset of API.