| name | qbittorrent-api |
| description | qBittorrent WebUI API reference covering authentication, sync, transfer, torrent, RSS, and search endpoints for qBittorrent 5.0+.
|
This WebUI API documentation applies to qBittorrent v5.0+. For other WebUI API versions, visit WebUI API.
Table of Contents
- Changes
- API v2.9.3
- API v2.11.3
- General information
- Authentication
- Login
- Logout
- Application
- Get application version
- Get API version
- Get build info
- Shutdown application
- Get application preferences
- Set application preferences
- Get default save path
- Get cookies
- Set cookies
- Log
- Get log
- Get peer log
- Sync
- Get main data
- Get torrent peers data
- Transfer info
- Get global transfer info
- Get alternative speed limits state
- Toggle alternative speed limits
- Get global download limit
- Set global download limit
- Get global upload limit
- Set global upload limit
- Ban peers
- Torrent management
- Get torrent list
- Get torrent generic properties
- Get torrent trackers
- Get torrent web seeds
- Get torrent contents
- Get torrent pieces' states
- Get torrent pieces' hashes
- Pause torrents
- Resume torrents
- Delete torrents
- Recheck torrents
- Reannounce torrents
- Edit trackers
- Remove trackers
- Add peers
- Add new torrent
- Add trackers to torrent
- Increase torrent priority
- Decrease torrent priority
- Maximal torrent priority
- Minimal torrent priority
- Set file priority
- Get torrent download limit
- Set torrent download limit
- Set torrent share limit
- Get torrent upload limit
- Set torrent upload limit
- Set torrent location
- Set torrent name
- Set torrent category
- Get all categories
- Add new category
- Edit category
- Remove categories
- Add torrent tags
- Remove torrent tags
- Get all tags
- Create tags
- RSS (experimental)
- Add folder
- Add feed
- Remove item
- Move item
- Get all items
- Mark as read
- Refresh item
- Set auto-downloading rule
- Rename auto-downloading rule
- Remove auto-downloading rule
- Get all auto-downloading rules
- Get all articles matching a rule
- Search
- Start search
- Stop search
- Get search status
- Get search results
- Delete search
- Get search plugins
- Install search plugin
- Uninstall search plugin
- Enable search plugin
- Update search plugins
- 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 |
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": "qBittorrent_notification@example.com",
"mail_notification_smtp": "smtp.changeme.com",
"mail_notification_ssl_enabled": false,
"mail_notification_username": "",
"max_active_downloads": 3,
"max_active_torrents": 5,
"max_active_uploads": 3,
"max_connec": 500,
"max_connec_per_torrent": 100,
"max_ratio": -1,
"max_ratio_act": 0,
"max_ratio_enabled": false,
"max_seeding_time": -1,
"max_seeding_time_enabled": false,
"max_uploads": -1,
"max_uploads_per_torrent": -1,
"outgoing_ports_max": 0,
"outgoing_ports_min": 0,
"pex": true,
"preallocate_all": false,
"proxy_auth_enabled": false,
"proxy_ip": "0.0.0.0",
"proxy_password": "",
"proxy_peer_connections": false,
"proxy_port": 8080,
"proxy_torrents_only": false,
"proxy_type": 0,
"proxy_username": "",
"queueing_enabled": false,
"random_port": false,
"recheck_completed_torrents": false,
"resolve_peer_countries": true,
"rss_auto_downloading_enabled":true,
"rss_download_repack_proper_episodes":true,
"rss_max_articles_per_feed":50,
"rss_processing_enabled":true,
"rss_refresh_interval":30,
"rss_smart_episode_filters":"s(\\d+)e(\\d+)\n(\\d+)x(\\d+)\n(\\d{4}[.\\-]\\d{1,2}[.\\-]\\d{1,2})",
"save_path": "/home/user/Downloads/",
"save_path_changed_tmm_enabled": false,
"save_resume_data_interval": 60,
"scan_dirs":
{
"/home/user/Downloads/incoming/games": 0,
"/home/user/Downloads/incoming/movies": 1,
},
"schedule_from_hour": 8,
"schedule_from_min": 0,
"schedule_to_hour": 20,
"schedule_to_min": 0,
"scheduler_days": 0,
"scheduler_enabled": false,
"send_buffer_low_watermark": 10,
"send_buffer_watermark": 500,
"send_buffer_watermark_factor": 50,
"slow_torrent_dl_rate_threshold": 2,
"slow_torrent_inactive_timer": 60,
"slow_torrent_ul_rate_threshold": 2,
"socket_backlog_size": 30,
"start_paused_enabled": false,
"stop_tracker_timeout": 1,
"temp_path": "/home/user/Downloads/temp",
"temp_path_enabled": false,
"torrent_changed_tmm_enabled": true,
"up_limit": 0,
"upload_choking_algorithm": 1,
"upload_slots_behavior": 0,
"upnp": true,
"use_https": false,
"utp_tcp_mixed_mode": 0,
"web_ui_address": "*",
"web_ui_ban_duration": 3600,
"web_ui_clickjacking_protection_enabled": true,
"web_ui_csrf_protection_enabled": true,
"web_ui_custom_http_headers": "",
"web_ui_domain_list": "*",
"web_ui_host_header_validation_enabled": true,
"web_ui_https_cert_path": "",
"web_ui_https_key_path": "",
"web_ui_max_auth_fail_count": 5,
"web_ui_port": 8080,
"web_ui_secure_cookie_enabled": true,
"web_ui_session_timeout": 3600,
"web_ui_upnp": false,
"web_ui_use_custom_http_headers_enabled": false,
"web_ui_username": "admin"
}
Set application preferences
Name: setPreferences
Parameters:
A json object with key-value pairs of the settings you want to change and their new values.
Example:
json={"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:
- There is no need to pass all possible preferences'
token:value pairs if you only want to change one option
- Paths in
scan_dirs must exist, otherwise this option will have no effect
- 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.
Get cookies
Name: cookies
Parameters:
None
Returns:
| HTTP Status Code | Scenario |
|---|
| 200 | All scenarios |
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 |
|---|
name | string | Cookie name |
domain | string | Cookie domain |
path | string | Cookie path |
value | string | Cookie value |
expirationDate | integer | Seconds since epoch |
Example:
[
{
"name":"Example",
"domain":"example.com",
"path":"/",
"value":"foo=bar"
"expirationDate":1507969127,
},
]
Set cookies
Name: setCookies
Parameters:
A json array of cookies to send when downloading .torrent files.
Each element of the array has the following properties:
| Property | Type | Description |
|---|
name | string? | Cookie name |
domain | string? | Cookie domain |
path | string? | Cookie path |
value | string? | Cookie value |
expirationDate | integer? | Seconds since epoch |
Returns:
| HTTP Status Code | Scenario |
|---|
| 200 | Cookies were saved |
| 400 | Request was not a valid json array of cookie objects |
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, stopped, active, inactive, running, 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 |
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 |
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: stop
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/stop?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: start
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/start?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="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 |
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 |
| |
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 |
url | string | The tracker URL you want to edit |
newUrl | string | The new URL to replace the url |
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 | url 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:
