Web UI API

NOTE: The following pieces of information are subject to change as the Web UI undergoes continued development. Already, several changes to the returned JSON have been proposed to the developers, so keep an eye out!

So um... I'm finding it annoying to flip through the Web UI forum looking for all the documentation on the stuff returned by µTorrent via specific URLs, so I'm just gonna list 'em all here in one place. If someone finds anything missing, feel free to post a new thread on your findings, and I'll incorporate it here. Or if Directrix ever gets around to it, edit this post/thread directly :P

For the curious, this thread is locked to keep it consistent and clean of discussions. It's here purely for reference. 😛

Unless otherwise noted, these APIs are called using HTTP GET.
A token authentication system was implemented in µTorrent in more recent versions to prevent cross-site request forgeries (CSRF).
Going forward, all developers creating applications that use the WebUI backend should remember to implement support for this system if at all possible, as the application will otherwise fail if the user has webui.token_auth enabled.
DO NOT IGNORE THE TOKEN AUTHENTICATION SYSTEM just for personal convenience.
&action=[SOME ACTION] requests that modify state (like stop/start/setprops), cannot be made by the guest account.
As well, getsettings cannot be cannot be used by the guest account.
If multiple hashes are accepted by a command, the hashes can be chained together like so:
http://[IP]:[PORT]/gui/?action=[ACTION]&hash=[TORRENT HASH 1]&hash=[TORRENT HASH 2]...&hash=[TORRENT HASH n]
When setting boolean values either by &action=setsetting or &action=setprops, the integer equivalent value should be sent as the value parameter rather than a string indicating true or false.
That is, if you wish to set a boolean value to true, then the value sent to the WebUI backend should be 1. If you wish to set a boolean value to false, a 0 should be sent to the backend.[/li]

Settings:

http://[iP]:[PORT]/gui/?action=getsettings

{

"build": BUILD NUMBER (integer),

"settings": [

[

OPTION NAME (string),

TYPE* (integer),

VALUE (string)

],

...

]

}

TYPE: The TYPE is an integer value that indicates what type of data is enclosed within the VALUE string. The following is a list of the possible TYPEs and what VALUE type it corresponds to:

0 = Integer
1 = Boolean
2 = String

OPTIONS: I would love to list every single one, but it's a bit much to be listing. Maybe another time? The option names are generally self-explanatory anyhow. For now, I guess I'll just list the more interesting ones:

max_dl_rate: The global download rate limit
max_ul_rate: The global upload rate limit

Right. Short list.

Changing settings:

http://[iP]:[PORT]/gui/?action=setsetting&s=[sETTING]&v=[VALUE]

This sets the specified property to the specified value for the torrent job. Multiple settings may be set simultaneously by with this action. Each v value is used as the value for the s property specified immediately before it.

EXAMPLE:

http://[iP]:[PORT]/gui/?action=setsetting&s=max_ul_rate&v=10&s=max_dl_rate&v=40

This will set the global upload rate limit to 10 KiB/s and the global download rate limit to 40 KiB/s.

Torrent/Labels List:

http://[iP]:[PORT]/gui/?list=1

{

"build": BUILD NUMBER (integer),

"label": [

[

LABEL (string),

TORRENTS IN LABEL (integer)

],

...

],

"torrents": [

[

HASH (string),

STATUS* (integer),

NAME (string),

SIZE (integer in bytes),

PERCENT PROGRESS (integer in per mils),

DOWNLOADED (integer in bytes),

UPLOADED (integer in bytes),

RATIO (integer in per mils),

UPLOAD SPEED (integer in bytes per second),

DOWNLOAD SPEED (integer in bytes per second),

ETA (integer in seconds),

LABEL (string),

PEERS CONNECTED (integer),

PEERS IN SWARM (integer),

SEEDS CONNECTED (integer),

SEEDS IN SWARM (integer),

AVAILABILITY (integer in 1/65536ths),

TORRENT QUEUE ORDER (integer),

REMAINING (integer in bytes)

],

...

],

"torrentc": CACHE ID** (string integer)

}

STATUS: The STATUS is a bitwise value, which is obtained by adding up the different values for corresponding statuses:

  1 = Started
  2 = Checking
  4 = Start after check
  8 = Checked
 16 = Error
 32 = Paused
 64 = Queued
128 = Loaded

For example, if a torrent job has a status of 201 = 128 + 64 + 8 + 1, then it is loaded, queued, checked, and started. A bitwise AND operator should be used to determine whether the given STATUS contains a particular status.

** CACHE ID: The CACHE ID is a number randomly generated by µTorrent for the given data. By asking µTorrent for the torrent list using http://[iP]:[PORT]/gui/?list=1****&cid=[CACHE ID], µTorrent will send only the items that have changed since it sent the torrent list with the corresponding CACHE ID. This is used for minimizing bandwidth usage and simplifying parsing of the output by decreasing the amount of data sent by µTorrent each time. When a CACHE ID is sent to µTorrent, two new dictionary keys replace "torrents," and the returned JSON will look as follows:

{

"build": BUILD NUMBER (integer),

"label": [

[

LABEL (string),

TORRENTS IN LABEL (integer)

],

...

],

"torrentp": [

[

HASH (string),

STATUS (integer),

NAME (string),

SIZE (integer in bytes),

PERCENT PROGRESS (integer in per mils),

DOWNLOADED (integer in bytes),

UPLOADED (integer in bytes),

RATIO (integer in per mils),

UPLOAD SPEED (integer in bytes per second),

DOWNLOAD SPEED (integer in bytes per second),

ETA (integer in seconds),

LABEL (string),

PEERS CONNECTED (integer),

PEERS IN SWARM (integer),

SEEDS CONNECTED (integer),

SEEDS IN SWARM (integer),

AVAILABILITY (integer in 1/65536ths),

TORRENT QUEUE ORDER (integer),

REMAINING (integer in bytes)

],

...

],

"torrentm": [

HASH (string),

...

]

"torrentc": CACHE ID (string integer)

}

The "torrentp" array contains a list of only the torrent jobs that have changed since µTorrent sent the list with the corresponding CACHE ID, and is identical to the "torrents" array in format (so it can be parsed in the same manner). The "torrentm" array contains a list of only the hashes of torrent jobs that have been removed since µTorrent sent the list with the corresponding CACHE ID.

SOURCE(S):

http://forum.utorrent.com/viewtopic.php?id=50779 (Lord Alderaan's explanation of the status bitfield, with a Javascript implementation)

http://forum.utorrent.com/viewtopic.php?pid=228008#p228008 (Lord Alderaan's comprehensive list for the "torrents" key values)

http://forum.utorrent.com/viewtopic.php?pid=212891#p212891 (Pleh's partial torrent status values list)

http://forum.utorrent.com/viewtopic.php?pid=258830#p258830 (Ryan Norton's remaining torrent status values list)

Files List:

http://[iP]:[PORT]/gui/?action=getfiles****&hash=[TORRENT HASH]

{

"build": BUILD NUMBER (integer),

"files": [

HASH (string),

[

[

FILE NAME (string),

FILE SIZE (integer in bytes),

DOWNLOADED (integer in bytes),

PRIORITY* (integer)

],

...

]

]

}

PRIORITY: The PRIORITY is an integer value that indicates the file's priority. The following is a list of the possible PRIORITY values and what priority it corresponds to:

0 = Don't Download
1 = Low Priority
2 = Normal Priority
3 = High Priority

It is possible to send multiple hashes to µTorrent by stringing one hash GET variable after another (?action=getfiles&hash=[TORRENT HASH 1]&hash=[TORRENT HASH 2]****&hash=...), but µTorrent will send multiple "files" key/value pairs in its JSON output (each formatted exactly as described above). I guess this behavior might be useful for people who want to preload file lists.

Torrent Job Properties:

http://[iP]:[PORT]/gui/?action=getprops****&hash=[TORRENT HASH]

{

"build": BUILD NUMBER (integer),

"props": [

{

"hash": HASH (string),

"trackers": TRACKERS* (string),

"ulrate": UPLOAD LIMIT (integer in bytes per second),

"dlrate": DOWNLOAD LIMIT (integer in bytes per second),

"superseed": INITIAL SEEDING** (integer),

"dht": USE DHT** (integer),

"pex": USE PEX** (integer),

"seed_override": OVERRIDE QUEUEING** (integer),

"seed_ratio": SEED RATIO (integer in per mils),

"seed_time": SEEDING TIME*** (integer in seconds),

"ulslots": UPLOAD SLOTS (integer)

}

]

}

TRACKER: This string is a list of the trackers used by the torrent job. Each newline is represented by a carriage return followed by a newline (\r\n).

** INITIAL SEEDING/USE DHT/USE PEX/OVERRIDE QUEUEING: These options are integer values that indicate their states. The following is a list of the possible values and what state it corresponds to:

-1 = Not allowed
 0 = Disabled
 1 = Enabled

*** SEEDING TIME: This is an integer representing the minimum amount of time (in seconds) that µTorrent should continue to seed after it has finished downloading the torrent. This value being set to 0 (zero) is equivalent to the seeding time being set to "(Ignore)".

Changing properties:

http://[iP]:[PORT]/gui/?action=setprops&hash=[TORRENT HASH]&s=[PROPERTY]****&v=[VALUE]

This sets the specified property to the specified value for the torrent job. Multiple properties (and in fact, multiple torrent jobs) may be set simultaneously by with this action. Each v value is used as the value for the s property specified immediately before it, and any property/value pair will be set for the last specified torrent (hash) in the chain of GET variables.

EXAMPLE:

http://[iP]:[PORT]/gui/?action=setprops&hash=[TORRENT HASH 1]&s=ulrate&v=10240&s=dlrate&v=20480&hash=[TORRENT HASH 2]&s=ulslots&v=4

This will set the torrent with [TORRENT HASH 1] to have an upload rate limit of 10 KiB/s and a download rate of 20 KiB/s, while simultaneously setting the torrent with [TORRENT HASH 2] to have 4 upload slots.

Changing labels:

http://[iP]:[PORT]/gui/?action=setprops&hash=[TORRENT HASH]&s=label****&v=[VALUE]

This action is specially documented because the label isn't returned in getprops (so changing labels is not obvious).

Actions:

Torrent Adding

http://[iP]:[PORT]/gui/?action=add-url****&s=[TORRENT URL]

This action adds a torrent job from the given URL. For servers that require cookies, cookies can be sent with the :COOKIE: method (see here). The string must be URL-encoded.

http://[iP]:[PORT]/gui/?action=add-file

This action is different from the other actions in that it uses HTTP POST instead of HTTP GET to submit data to µTorrent. The HTTP form must use an enctype of "multipart/form-data" and have an input field of type "file" with name "torrent_file" that stores the local path to the file to upload to µTorrent.

Basic Actions

http://[iP]:[PORT]/gui/?action=start****&hash=[TORRENT HASH]

This action tells µTorrent to start the specified torrent job(s). Multiple hashes may be specified to act on multiple torrent jobs.

http://[iP]:[PORT]/gui/?action=stop****&hash=[TORRENT HASH]

This action tells µTorrent to stop the specified torrent job(s). Multiple hashes may be specified to act on multiple torrent jobs.

http://[iP]:[PORT]/gui/?action=pause****&hash=[TORRENT HASH]

This action tells µTorrent to pause the specified torrent job(s). Multiple hashes may be specified to act on multiple torrent jobs.

http://[iP]:[PORT]/gui/?action=unpause****&hash=[TORRENT HASH]

This action tells µTorrent to unpause the specified torrent job(s). Multiple hashes may be specified to act on multiple torrent jobs.

http://[iP]:[PORT]/gui/?action=forcestart****&hash=[TORRENT HASH]

This action tells µTorrent to force the specified torrent job(s) to start. Multiple hashes may be specified to act on multiple torrent jobs.

http://[iP]:[PORT]/gui/?action=recheck****&hash=[TORRENT HASH]

This action tells µTorrent to recheck the torrent contents for the specified torrent job(s). Multiple hashes may be specified to act on multiple torrent jobs.

http://[iP]:[PORT]/gui/?action=remove****&hash=[TORRENT HASH]

This action removes the specified torrent job(s) from the torrent jobs list. Multiple hashes may be specified to act on multiple torrent jobs. This action currently ignores the "Move to trash if possible" option in µTorrent 1.7.x, though that'll change in µTorrent 1.8 (post build 9272).

http://[iP]:[PORT]/gui/?action=removedata****&hash=[TORRENT HASH]

This action removes the specified torrent job(s) from the torrent jobs list and removes the corresponding torrent contents (data) from disk. Multiple hashes may be specified to act on multiple torrent jobs. This action currently ignores the "Move to trash if possible" option in µTorrent 1.7.x, though that'll change in µTorrent 1.8 (post build 9272).

http://[iP]:[PORT]/gui/?action=setprio&hash=[TORRENT HASH]&p=[PRIORITY]****&f=[FILE INDEX]

This action sets the priority for the specified file(s) in the torrent job. The possible priority levels are the values returned by "getfiles". A file is specified using the zero-based index of the file in the inside the list returned by "getfiles". Only one priority level may be specified on each call to this action, but multiple files may be specified.

Queue Management

http://[iP]:[PORT]/gui/?action=queuebottom****&hash=[TORRENT HASH]

This action tells µTorrent to move the specified torrent to the bottom of the queue.

http://[iP]:[PORT]/gui/?action=queuedown****&hash=[TORRENT HASH]

This action tells µTorrent to move the specified torrent one position down the queue.

http://[iP]:[PORT]/gui/?action=queuetop****&hash=[TORRENT HASH]

This action tells µTorrent to move the specified torrent to the top of the queue.

http://[iP]:[PORT]/gui/?action=queueup****&hash=[TORRENT HASH]

This action tells µTorrent to move the specified torrent one position up the queue.

Remarks:

Multiple hashes may be strung together to change torrent queue order in batches, but the order in which the queue order changes are applied is the order in which the hashes are listed as GET parameters. As an example, see the following:

/gui/?action=queueup&hash=[TORRENT B QUEUED AT 2]&hash=[TORRENT A QUEUED AT 1]

This request will effectively result in nothing having happened. Why? Because the backend will first push TORRENT B up the queue to 1st, which pushes TORRENT A down the queue to 2nd. Then it will apply queueup on TORRENT A afterwards, which pushes it back up from 2nd to 1st (leaving TORRENT B back at 2nd).

All the other requests behave similarly as well. Essentially, in most situations, if torrent hashes are going to be batched up into one request, clients should sorted the list in queue order.

queueup and queuebottom should be sent hash lists sorted in ascending queue order

queuedown and queuetop should be sent hash lists sorted in descending queue order

Provide feedback

Saved searches

Use saved searches to filter your results more quickly