Skip to content

Latest commit

 

History

History
3309 lines (2506 loc) · 121 KB

WebUI-API-(qBittorrent-4.1).md

File metadata and controls

3309 lines (2506 loc) · 121 KB

This WebUI API documentation applies to qBittorrent v4.1+. For other WebUI API versions, visit WebUI API.

Table of Contents

  1. Changes
    1. API v2.0
    2. API v2.0.1
    3. API v2.0.2
    4. API v2.1.0
    5. API v2.1.1
    6. API v2.2.0
    7. API v2.2.1
    8. API v2.3.0
    9. API v2.4.0
    10. API v2.4.1
    11. API v2.5.0
    12. API v2.5.1
    13. API v2.6.0
    14. API v2.6.1
    15. API v2.6.2
    16. API v2.7.0
    17. API v2.8.0
    18. API v2.8.1
    19. API v2.8.2
    20. API v2.8.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
  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.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)
  • Add /torrents/setShareLimits/ method (#8598)

API v2.0.2

  • Add /torrents/reannounce method (#9229)

API v2.1.0

  • Change /sync/maindata categories field from array to object (#9228)
  • Add savePath field to /torrents/createCategory (#9228). This method now requires the category to already exist and will not create new categories.
  • Add /torrents/editCategory method (#9228)

API v2.1.1

  • Add /torrents/categories method (#9586)
  • Add /search/ methods (#8584)
  • Add free_space_on_disk field to /sync/maindata (#8217)

API v2.2.0

  • Add /torrents/editTracker and /torrents/removeTracker methods (#9375)
  • Add tier, num_seeds, num_leeches, and num_downloaded fields to /torrents/trackers (#9375)
  • Change status field from translated string to an integer for /torrents/trackers (#9375)
  • Change /torrents/filePrio id field to accept multiple ids (#9541)
  • Throw additional errors for failed requests to /torrents/filePrio (#9541)
  • Add autoTMM field to /torrents/add (#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)

API v2.2.1

  • Add rss/refreshItem (#11067)

API v2.3.0

  • Remove web_ui_password field from /app/preferences, this field is still writable in /app/setPreferences method (#9942)
  • Add /app/buildInfo method (#10096)
  • Always use / as path separator in /torrents/files response (#10153)
  • Add /torrents/addPeers and /transfer/banPeers methods (#10158)
  • Add /torrents/addTags, /torrents/removeTags, /torrents/tags, /torrents/createTags, /torrents/deleteTags methods (#10527)

API v2.4.0

  • Add /torrents/renameFile method (#11029)

API v2.4.1

  • Add stalled, stalled_uploading and stalled_downloading as possible values for the filter parameter in /torrents/info (#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, #11726, #12004, #11834)

API v2.5.0

  • Removes enable_super_seeding as fields from /app/preferences and /app/setPreferences (#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, #12549)
  • Add /rss/markAsRead and /rss/matchingArticles methods (#12549)

API v2.6.0

  • Removed /search/categories method and modified /search/plugins method's response (#12705)

API v2.6.1

  • Exposed contentPath via the content_path field in the response to /torrents/info (#13625)

API v2.6.2

  • Added tags optional field to /torrents/add (#13882)

API v2.8.0

  • Added /torrents/renameFolder method and modified /torrents/renameFile method's parameters (#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 for details)

API v2.8.1

  • Added ratioLimit and seedingTimeLimit optional fields to /torrents/add (#14519)
  • Added seeding_time field to /torrents/info (#14554)

API v2.8.2

  • Added indexes optional parameter to /torrents/files (#14795)
  • Added index field to /torrents/files response (#14795)

API v2.8.3

  • Added tag optional parameter to /torrents/info (#15152)

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 qBittorent 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 qBittorent 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 qBittorent 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 qBittorent 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 bool True enables os cache
enable_upload_suggestions bool True enables sending of upload piece suggestions
file_pool_size integer File pool size
outgoing_ports_max integer Maximal outgoing port (0: Disabled)
outgoing_ports_min integer Minimal outgoing port (0: Disabled)
recheck_completed_torrents bool True rechecks torrents on completion
resolve_peer_countries bool True resolves peer countries
save_resume_data_interval integer Save resume data interval in min
send_buffer_low_watermark integer Send buffer low watermark in KiB
send_buffer_watermark integer Send buffer watermark in KiB
send_buffer_watermark_factor integer Send buffer watermark factor in percent
socket_backlog_size integer Socket backlog size
upload_choking_algorithm integer Upload choking algorithm used (see list of possible values below)
upload_slots_behavior integer Upload slots behavior used (see list of possible values below)
upnp_lease_duration integer UPnP lease duration (0: Permanent lease)
utp_tcp_mixed_mode integer μ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:

{
    "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": "[email protected]",
    "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={"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
  2. Paths in scan_dirs must exist, otherwise this option will have no effect
  3. 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 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:

/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 Seconds since epoch (Note: switched from milliseconds to seconds in v4.5.0)
type integer Type of the message: Log::NORMAL: 1, Log::INFO: 2, Log::WARNING: 4, Log::CRITICAL: 8

Example:

[
    {
        "id":0,
        "message":"qBittorrent v3.4.0 started",
        "timestamp":1507969127,
        "type":1
    },
    {
        "id":1,
        "message":"qBittorrent is trying to listen on any interface port: 19036",
        "timestamp":1507969127,
        "type":2
    },
    {
        "id":2,
        "message":"Peer ID: -qB3400-",
        "timestamp":1507969127,
        "type":1
    },
    {
        "id":3,
        "message":"HTTP User-Agent is 'qBittorrent/3.4.0'",
        "timestamp":1507969127,
        "type":1
    },
    {
        "id":4,
        "message":"DHT support [ON]",
        "timestamp":1507969127,
        "type":2
    },
    {
        "id":5,
        "message":"Local Peer Discovery support [ON]",
        "timestamp":1507969127,
        "type":2
    },
    {
        "id":6,
        "message":"PeX support [ON]",
        "timestamp":1507969127,
        "type":2
    },
    {
        "id":7,
        "message":"Anonymous mode [OFF]",
        "timestamp":1507969127,
        "type":2
    },
    {
        "id":8,
        "message":"Encryption support [ON]",
        "timestamp":1507969127,
        "type":2
    },
    {
        "id":9,
        "message":"Embedded Tracker [OFF]",
        "timestamp":1507969127,
        "type":2
    },
    {
        "id":10,
        "message":"UPnP / NAT-PMP support [ON]",
        "timestamp":1507969127,
        "type":2
    },
    {
        "id":11,
        "message":"Web UI: Now listening on port 8080",
        "timestamp":1507969127,
        "type":1
    },
    {
        "id":12,
        "message":"Options were saved successfully.",
        "timestamp":1507969128,
        "type":1
    },
    {
        "id":13,
        "message":"qBittorrent is successfully listening on interface :: port: TCP/19036",
        "timestamp":1507969128,
        "type":2
    },
    {
        "id":14,
        "message":"qBittorrent is successfully listening on interface 0.0.0.0 port: TCP/19036",
        "timestamp":1507969128,
        "type":2
    },
    {
        "id":15,
        "message":"qBittorrent is successfully listening on interface 0.0.0.0 port: UDP/19036",
        "timestamp":1507969128,
        "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 Seconds 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:

/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 bool Whether the response contains all the data or partial data
torrents object Property: torrent hash, value: same as torrent list
torrents_removed array List of hashes of torrents removed since last request
categories object Info for categories added since last request
categories_removed array List of categories removed since last request
tags array List of tags added since last request
tags_removed array List of tags removed since last request
server_state object Global transfer info

Example:

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

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:

/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 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:

{
    "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"). Remember to URL-encode the category name. For example, My category becomes My%20category
tag optional since 2.8.3 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's JSON array (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 |

Example:

/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 unlimited.
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
isPrivate bool True if torrent is from a private tracker (added in 5.0.0)
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 string Torrent state. See table here below for the possible values
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 unlimited.
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:

[
    {
        "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,
        "isPrivate":true
    },
    {
        another_torrent_info
    }
]

Get torrent generic properties

Requires knowing the torrent hash. You can get it from 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:

  • empty, if the torrent hash is invalid
  • otherwise, a JSON object with 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)
isPrivate bool True if torrent is from a private tracker

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

Example:

{
    "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,
    "isPrivate":true,
    "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.

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 downloads 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:

[
    {
        "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.

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:

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

Get torrent contents

Requires knowing the torrent hash. You can get it from torrent list.

Name: files

Parameters:

Parameter Type Description
hash string The hash of the torrent you want to get the contents of
indexes optional since 2.8.2 string The indexes of the files you want to retrieve. indexes can contain multiple values separated by |.

Returns:

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

The response is:

  • empty, if the torrent hash is invalid
  • otherwise, a JSON array, where each element contains info about one file, with the following fields
Property Type Description
index since 2.8.2 integer File index
name string File name (including relative path)
size integer File size (bytes)
progress float File progress (percentage/100)
priority integer File priority. See possible values here below
is_seed 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
6 High priority
7 Maximal priority

Example:

[
    {
        "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.

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:

  • empty, if the torrent hash is invalid
  • otherwise, an array of states (integers) of all pieces (in order) of a specific torrent.

Value meanings are defined as below:

Value Description
0 Not downloaded yet
1 Now downloading
2 Already downloaded

Example:

[0,0,2,1,0,0,2,1]

Get torrent pieces' hashes

Requires knowing the torrent hash. You can get it from 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:

  • empty, if the torrent hash is invalid
  • otherwise, an array of hashes (strings) of all pieces (in order) of a specific torrent.

Example:

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

Pause torrents

Requires knowing the torrent hashes. You can get it from 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 |, to pause multiple torrents, or set to all, to pause all torrents.

Example:

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

Name: resume

Parameters:

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

Example:

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

Name: delete

Parameters:

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

Example:

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

Name: recheck

Parameters:

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

Example:

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

Name: reannounce

Parameters:

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

Example:

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

Add torrent from URLs example:

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:

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

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 since 2.8.1 float Set torrent share ratio limit
seedingTimeLimit optional since 2.8.1 integer Set torrent seeding time limit. Unit in minutes
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.

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 |

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.

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 |, to increase the priority of multiple torrents, or set to all, to increase the priority of all torrents.

Example:

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

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 |, to decrease the priority of multiple torrents, or set to all, to decrease the priority of all torrents.

Example:

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

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 |, to set multiple torrents to the maximum priority, or set to all, to set all torrents to the maximum priority.

Example:

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

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 |, to set multiple torrents to the minimum priority, or set to all, to set all torrents to the minimum priority.

Example:

/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 |
priority number File priority to set (consult torrent contents API for possible values)

id values correspond to file position inside the array returned by torrent contents API, e.g. id=0 for first file, id=1 for second file, etc.

Since 2.8.2 it is recommended to use index field returned by torrent contents API (since the files can be filtered and the index value may differ from the position inside the response array).

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.

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

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.

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 (minutes) 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.

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

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.

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.

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.

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

{
    "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

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

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

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.

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.

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

[
    "Tag 1",
    "Tag 2"
]

Returns:

HTTP Status Code Scenario
200 All scenarios

Create tags

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

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.

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.

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 |, to toggle sequential download for multiple torrents, or set to all, to toggle sequential download for all torrents.

Example:

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

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 |, 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:

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

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.

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")
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.:

{
    "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.:

{
    "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.:

{
    "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.:

{
    "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 |. 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:

{
    "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:

[
    {
        "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:

{
    "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
[
    {
        "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"
    }
]

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"). Supports multiple sources separated by |

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 |

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