Last active
September 21, 2021 23:33
-
-
Save pmzqla/7e5733dbecfc50ee4ecd to your computer and use it in GitHub Desktop.
qBittorrent Web API documentation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| See the official documentation here: https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-Documentation | |
| ---- | |
| qBittorrent Web API | |
| API version: 2 | |
| GET METHODS | |
| =========== | |
| - Get version info | |
| - Get torrent list | |
| - Get torrent trackers | |
| - Get torrent generic properties | |
| - Get torrent contents | |
| - Get global transfer info | |
| - Get partial data | |
| - Get qBittorrent preferences | |
| POST METHODS | |
| ============ | |
| - Authentication | |
| - Set sequential download state | |
| - Set first/last piece priority | |
| - Set force start | |
| - Pause all the torrents | |
| - Resume all the torrents | |
| In this file there are mainly reported the changes since v3.10.12. | |
| If something is mentioned in the official documentation but not here, | |
| then it's still valid. | |
| Look for * in this page to find the changes since v3.10.12 | |
| Note: /json/ was renamed to /query/ | |
| Get version info | |
| ---------------- | |
| No authentication required. Answer: plain text | |
| *GET /version/api - current Web API version | |
| *GET /version/api_min - return minimum Web API version supported | |
| *GET /version/qbittorrent - return current qBittorrent version | |
| Get torrent list | |
| ---------------- | |
| GET /query/torrents | |
| Authentication required | |
| *Params (available since v3.2.0) | |
| - filter (string): all, downloading, completed, paused, active, inactive | |
| - label (string): get torrents with the given label (empty string means "unlabeled"; no "label" param means "any label") | |
| - sort (string): sort torrents by given key | |
| - reverse (bool): enable reverse sorting | |
| - limit (int): limit number of torrents returned | |
| - offset (int): set offset (if less than 0, offset from end) | |
| example: /query/torrents?filter=all&sort=size&reverse=false | |
| Response: Array of objects. Each object has the followings: | |
| key | type | Description | |
| --------------------------------------- | |
| hash string Torrent hash | |
| name string Torrent name | |
| *size integer Torrent size (bytes) | |
| progress float Torrent progress (%/100) | |
| *dlspeed integer Torrent download speed (bytes/s) | |
| *upspeed integer Torrent upload speed (bytes/s) | |
| *priority integer Torrent priority. Returns -1 if queuing is disabled | |
| *num_seeds integer Torrent seeds connected to | |
| *num_complete integer Torrent seeds in the swarm | |
| *num_leechs integer Torrent leechers connected to | |
| *num_incomplete integer Torrent leechers in the swarm | |
| *ratio float Torrent share ratio. Max ratio value: 9999. | |
| *eta integer Torrent ETA (seconds) | |
| state string Torrent state. See possible values here below | |
| *seq_dl bool True if sequential download is enabled | |
| *f_l_piece_prio bool True if first last piece are prioritized | |
| Possible values of 'state': | |
| error - some error occurred, applies to paused torrents | |
| pausedUP - torrent is paused and has finished downloading | |
| pausedDL - torrent is paused and has NOT finished downloading | |
| queuedUP - queuing is enabled and torrent is queued for upload | |
| queuedDL - queuing is enabled and torrent is queued for download | |
| uploading - torrent is being seeded and data is being transfered | |
| stalledUP - torrent is being seeded, but no connection were made | |
| checkingUP - torrent has finished downloading and is being checked; | |
| this status also applies to preallocation (if enabled) | |
| and checking resume data on qBt startup | |
| checkingDL - same as checkingUP, but torrent has NOT finished downloading | |
| downloading - torrent is being downloaded and data is being transfered | |
| stalledDL - torrent is being downloaded, but no connection were made | |
| Note: -1 is returned for integers when info is not known. | |
| Get torrent trackers | |
| -------------------- | |
| GET /query/propertiesTrackers/TORRENT_HASH | |
| Authentication required | |
| JSON formatted data | |
| key | type | Description | |
| --------------------------------------- | |
| url string Tracker URL | |
| status string Tracker status | |
| num_peers integer Tracker peer count | |
| msg string Tracker message (last) | |
| Get torrent generic properties | |
| ------------------------------ | |
| GET /query/propertiesGeneral/TORRENT_HASH | |
| Authentication required | |
| JSON formatted data | |
| key | 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 uploaded 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 | |
| Note: -1 is returned for integers when info is not known. | |
| Get torrent contents | |
| -------------------- | |
| GET /query/propertiesFiles/TORRENT_HASH | |
| Authentication required | |
| JSON formatted data | |
| key | type | Description | |
| --------------------------------------- | |
| *name string File name (including relative path) | |
| *size integer File size (bytes) | |
| progress float File progress (%/100) | |
| priority integer File priority. See possible values here below | |
| is_seed bool True if file is seeding/complete | |
| Possible values of 'priority' | |
| 0 - do not download | |
| 1 - normal priority | |
| 2 - high priority | |
| 7 - maximal priority | |
| Get global transfer info | |
| ------------------------ | |
| GET /query/transferInfo | |
| Authentication required | |
| JSON formatted data | |
| key | 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 | |
| Possible values of 'connection_status' | |
| connected | |
| firewalled | |
| disconnected | |
| Get partial data (available since 3.2.0) | |
| --------------------------- | |
| *GET /sync/maindata | |
| Authentication required | |
| Response: JSON formatted data | |
| Params: | |
| - rid: response ID | |
| example: /sync/maindata?rid=14 | |
| - If no rid is given, rid=0 will be assumed. If the given rid is different from the one of | |
| the last server response, full_update will be true. | |
| key | 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 /query/propertiesGeneral/TORRENT_HASH | |
| torrents_removed array list of hashes of torrents removed since last request | |
| labels array list of labels added since last request | |
| labels_removed array list of labels removed since last request | |
| queueing bool priority system usage flag | |
| server_state object Same as /query/transferInfo | |
| Get qBittorrent preferences (mostly unchanged since v3.10.11) | |
| --------------------------- | |
| GET /query/preferences | |
| Authentication required | |
| JSON formatted data | |
| key | type | Description | |
| ----------------------------------------------------- | |
| locale string currently selected language (e.g. en_GB for english) | |
| save_path string default save path for torrents | |
| temp_path_enabled bool true if folder for incomplete torrents is enabled | |
| temp_path string path for incomplete torrents | |
| scan_dirs array each element of the array contains a string that is the path to a watched folder | |
| download_in_scan_dirs array each element of the array contains a bool. If nth bool is true, torrents from nth 'scan_dirs' are downloaded in nth 'scan_dirs' | |
| export_dir_enabled bool true if .torrent file should be copied to 'export_dir' when added | |
| export_dir string path to directory were .torrent files are copied if export_dir_enabled is true | |
| mail_notification_enabled bool true if e-mail notification should be enabled | |
| 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 path to program with arguemnts. %f and %n will be replaced with the path to the torrent and the name of the torrent respectively | |
| preallocate_all bool true if file preallocation should take place, otherwise sparse files are used | |
| 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 | |
| incomplete_files_ext bool if true .!qB extension will be appended to incomplete files | |
| listen_port integer port for incoming connections | |
| upnp bool true if UPnP/NAT-PMP is enabled | |
| 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_uploads integer maximum global number of upload slots | |
| max_connec_per_torrent integer maximum number of simultaneous connections per torrent | |
| max_uploads_per_torrent integer maximum number of upload slots per torrent | |
| enable_utp bool true if uTP protocol should be enabled (libtorrent >= 0.16) | |
| limit_utp_rate bool true if [du]l_limit should be applied to uTP connections (libtorrent >= 0.16) | |
| limit_tcp_overhead bool true if [du]l_limit should be applied to estimated TCP overhead (service data: e.g. packet headers) | |
| 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 | |
| dhtSameAsBT bool true if DHT port should match TCP port | |
| pex bool true if PeX is enabled | |
| lsd bool true if LSD is eanbled | |
| encryption integer encryption state. See possible values here below | |
| anonymous_mode bool if true anonymous mode will be enabled (libtorrent >= 0.16) | |
| proxy_type integer proxy type. See 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 (libtorrent >= 0.16) | |
| 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 | |
| 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 | |
| web_ui_port integer WebUI port | |
| web_ui_username string WebUI username | |
| web_ui_password string MD5 hash of WebUI password | |
| bypass_local_auth bool true if authentication challenge for loopback address (127.0.0.1) should be disabled | |
| use_https bool true if WebUI HTTPS access is eanbled | |
| ssl_key string SSL keyfile contents (this is a not a path) | |
| ssl_cert string SSL certificate contents (this is a not a path) | |
| dyndns_enabled bool true if server DNS should be updated dynamically | |
| dyndns_service integer DDNS service. See 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 | |
| Possible values of 'scheduler_days': | |
| 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 'dyndns_service': | |
| 0 - use DyDNS | |
| 1 - use NOIP | |
| Possible values of 'encryption' | |
| 0 - prefer encryption (default): allow both encrypted and unencrypted connections | |
| 1 - force encryption on: allow only encrypted connections | |
| 2 - force encryption off: allow only unencrypted connection | |
| Possible values of 'proxy_type': | |
| -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 | |
| Authentication | |
| ---------------- | |
| The new authentication method uses cookies. On succesfull login the server replies with a | |
| cookie named SID. This cookie has to be supplied for every request that requires authentication. | |
| *POST /login | |
| Params: | |
| - username | |
| - password | |
| Set sequential download state | |
| ---------------- | |
| *POST /command/toggleSequentialDownload | |
| Authentication required | |
| Params: | |
| - hashes: list of torrent hashes separated by | (e.g. hashes=HASH1|HASH2|...) | |
| Set first/last piece priority | |
| ---------------- | |
| *POST /command/toggleFirstLastPiecePrio | |
| Authentication required | |
| Params: | |
| - hashes: list of torrent hashes separated by | (e.g. hashes=HASH1|HASH2|...) | |
| Set force start | |
| ---------------- | |
| *POST /command/setForceStart | |
| Authentication required | |
| Params: | |
| - hashes: list of torrent hashes separated by | (e.g. hashes=HASH1|HASH2|...) | |
| - value: true|false | |
| Pause all the torrents | |
| ---------------- | |
| *POST /command/pauseAll # it was pauseall | |
| Authentication required | |
| Resume all the torrents | |
| ---------------- | |
| *POST /command/resumeAll # it was resumeeall | |
| Authentication required |
I'm sorry, I currently don't have much free time and to be honest, I haven't looked into the new authentication method that much. The code was written by glassez, I'm sure he can be more helpful than me.
Anyway, it seems a standard implementation.
On successful login, the server includes in the HTTP header Set-Cookie:SID=XXXXXX; path=/.
To perform actions that require authorization, you just need to include Cookie:SID=XXXXXX in the HTTP header of the request.
Example using curl:
curl -v --data "username=XXX&password=XXX" http://localhost:8080/login
# get the value of SID in the response header
curl http://localhost:8080/query/transferInfo --cookie "SID=IscHZUzkFE8nJDgGaIkaFvucMgQE9SQm"
# and to close the session
curl http://localhost:8080/logout --cookie "SID=IscHZUzkFE8nJDgGaIkaFvucMgQE9SQm"
As far as I know, browsers do everything automatically.
EDIT:
Sorry if I replied only now, it seems that there are no notifications for comments on gist.
pmzqla thanks,
Using the standard implementation does works. In few days I would release my Android app with the new method.
Best regards!
I've just updated the documentation including filters and partial data. I hope I haven't done any mistake.
Thanks pmzqla,
I really appreciate the documentation. I will use the filter and partial data for improving requests...by the way, any change to publish methods in the API for the search engine?
No, it's currently not possible to interact with the search engine through the API.
Hi pmzqla,
What about labels? will there be options for handling labels?
There's a pending pull request. If it is merged, I'll update the documentation when I have time.
PS: there are no notifications for comments on gist, so please send me an email if you have a question or post the question somewhere else. I never open this page if not for particular reasons.
pmzqla.git at gmail.com
Additional changes for v2 that I've found during testing:
POST METHODS
============
- Get torrent download limits
- Set torrent download limits
- Get torrent upload limits
- Set torrent upload limits
Get torrent download limits (available since 3.2.0)
- /command/getTorrentDlLimit url changed to /command/getTorrentsDlLimit (note the pluralization)
---------------------------
*POST /command/getTorrentsDlLimit
Authentication required
Response: JSON formatted data
Params:
- hashes: One or more hashes separated with '|'
Returns:
- json={"hash1": integer,"hash2": integer}
Set torrent download limits (available since 3.2.0)
- /command/setTorrentDlLimit url changed to /command/setTorrentsDlLimit (note the pluralization)
---------------------------
*POST /command/setTorrentsDlLimit
Authentication required
Params:
- hashes: One or more hashes separated with '|'
- limit: torrent download speeds in bytes
Get torrent upload limits (available since 3.2.0)
- /command/getTorrentUpLimit url changed to /command/getTorrentsUpLimit (note the pluralization)
---------------------------
*POST /command/getTorrentsUpLimit
Authentication required
Response: JSON formatted data
Params:
- hashes: One or more hashes separated with '|'
Returns:
- json={"hash1": integer,"hash2": integer}
Set torrent upload limits (available since 3.2.0)
- /command/setTorrentUpLimit url changed to /command/setTorrentsUpLimit (note the pluralization)
---------------------------
*POST /command/setTorrentsUpLimit
Authentication required
Params:
- hashes: One or more hashes separated with '|'
- limit: torrent upload speeds in bytes
Thanks jmcaffee I didn't notice the change and forgot it.
FYI, the documentation is now available in the official wiki.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Hi pmzqla,
I would be helpful having a documentation on how to authenticate with the new cookie based method.