qbittorrent-api

This WebUI API documentation applies to qBittorrent v5.0+. For other WebUI API versions, visit WebUI API.

Table of Contents

1. Changes
   1. API v2.9.3
   2. API v2.11.3
2. General information
3. Authentication
   1. Login
   2. Logout
4. Application
   1. Get application version
   2. Get API version
   3. Get build info
   4. Shutdown application
   5. Get application preferences
   6. Set application preferences
   7. Get default save path
   8. Get cookies
   9. Set cookies
5. Log
   1. Get log
   2. Get peer log
6. Sync
   1. Get main data
   2. Get torrent peers data
7. Transfer info
   1. Get global transfer info
   2. Get alternative speed limits state
   3. Toggle alternative speed limits
   4. Get global download limit
   5. Set global download limit
   6. Get global upload limit
   7. Set global upload limit
   8. Ban peers
8. Torrent management
   1. Get torrent list
   2. Get torrent generic properties
   3. Get torrent trackers
   4. Get torrent web seeds
   5. Get torrent contents
   6. Get torrent pieces' states
   7. Get torrent pieces' hashes
   8. Pause torrents
   9. Resume torrents
   10. Delete torrents
   11. Recheck torrents
   12. Reannounce torrents
   13. Edit trackers
   14. Remove trackers
   15. Add peers
   16. Add new torrent
   17. Add trackers to torrent
   18. Increase torrent priority
   19. Decrease torrent priority
   20. Maximal torrent priority
   21. Minimal torrent priority
   22. Set file priority
   23. Get torrent download limit
   24. Set torrent download limit
   25. Set torrent share limit
   26. Get torrent upload limit
   27. Set torrent upload limit
   28. Set torrent location
   29. Set torrent name
   30. Set torrent category
   31. Get all categories
   32. Add new category
   33. Edit category
   34. Remove categories
   35. Add torrent tags
   36. Remove torrent tags
   37. Get all tags
   38. Create tags
   39. Delete tags
   40. Set automatic torrent management
   41. Toggle sequential download
   42. Set first/last piece priority
   43. Set force start
   44. Set super seeding
   45. Rename file
   46. Rename folder
9. RSS (experimental)
   1. Add folder
   2. Add feed
   3. Remove item
   4. Move item
   5. Get all items
   6. Mark as read
   7. Refresh item
   8. Set auto-downloading rule
   9. Rename auto-downloading rule
   10. Remove auto-downloading rule
   11. Get all auto-downloading rules
   12. Get all articles matching a rule
10. Search
    1. Start search
    2. Stop search
    3. Get search status
    4. Get search results
    5. Delete search
    6. Get search plugins
    7. Install search plugin
    8. Uninstall search plugin
    9. Enable search plugin
    10. Update search plugins
11. WebAPI versioning

---

Changes

API v2.9.3

• Added reannounce to /torrents/info (#19571)

API v2.11.3

• Add APIs for managing cookies` (#21340)
• Remove cookie field from /torrents/add request

General Information

• All API methods follows the format /api/v2/APIName/methodName, where APIName is a certain subgroup of API methods whose functionality is related.
• All API methods only allows GET or POST methods. Use POST when you are mutating some state (or when your request is too big to fit into GET) and use GET otherwise. Starting with qBittorrent v4.4.4, server will return 405 Method Not Allowed when you used the wrong request method.
• All API methods require authentication (except /api/v2/auth/login, 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:

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

Possible fields:

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