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` ```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.