transmission-api

[!IMPORTANT] Transmisson 4.1.0 (rpc_version_semver 6.0.0) added support for the JSON-RPC 2.0 protocol and converted all RPC strings to snake_case.

The old bespoke RPC protocol, and the old mix of kebab-case and camelCase strings, are still supported in Transmission 4 but are deprecated and will be removed in the future. People using the old protocol should update their code!

For documentation of the old RPC protocol and strings, please consult documentation from previous versions. https://github.com/transmission/transmission/blob/4.0.6/docs/rpc-spec.md

Transmission's RPC specification

This document describes a protocol for interacting with Transmission sessions remotely.

1.1 Terminology

The JSON terminology in RFC 8259 is used. RPC requests and responses are formatted in JSON.

1.2 Tools

If transmission-remote is called with a --debug argument, its RPC traffic to the Transmission server will be dumped to the terminal. This can be useful when you want to compare requests in your application to another for reference.

If transmission-qt is run with an environment variable TR_RPC_VERBOSE set, it too will dump the RPC requests and responses to the terminal for inspection.

Lastly, using the browser's developer tools in the Transmission web client is always an option.

1.3 Libraries of ready-made wrappers

Some people outside of the Transmission project have written libraries that wrap this RPC API. These aren't supported by the Transmission project, but are listed here in the hope that they may be useful:

Language	Link
C# .NET10	https://www.nuget.org/packages/Transmission.API.RPC.NET/
C#	https://www.nuget.org/packages/Transmission.API.RPC
Go	https://github.com/hekmon/transmissionrpc
Python	https://github.com/Trim21/transmission-rpc
Rust	https://crates.io/crates/transmission-rpc

2 Message format

Transmission follows the JSON-RPC 2.0 specification and supports the entirety of it, except that parameters by-position is not supported, meaning the request parameters must be an Object.

Response parameters are returned in the result Object.

Example request

{
   "jsonrpc": "2.0",
   "params": {
     "fields": [ "version" ]
   },
   "method": "session_get",
   "id": 912313
}

Example response

{
   "jsonrpc": "2.0",
   "result": {
      "version": "4.1.0-dev (ae226418eb)"
   },
   "id": 912313
}

2.1 Error data

JSON-RPC 2.0 allows for additional information about an error be included in the data key of the Error object in an implementation-defined format.

In Transmission, this key is an Object that includes:

1. An optional error_string string that provides additional information that is not included in the message key of the Error object.
2. An optional result Object that contains additional keys defined by the method.

{
   "jsonrpc": "2.0",
   "error": {
      "code": 7,
      "message": "HTTP error from backend service",
      "data": {
         "error_string": "Couldn't test port: No Response (0)",
         "result": {
            "ip_protocol": "ipv6"
         }
      }
   },
   "id": 912313
}

2.2 Transport mechanism

HTTP POSTing a JSON-encoded request is the preferred way of communicating with a Transmission RPC server. The current Transmission implementation has the default URL as http://host:9091/transmission/rpc. Clients may use this as a default, but should allow the URL to be reconfigured, since the port and path may be changed to allow mapping and/or multiple daemons to run on a single server.

The RPC server will normally return HTTP 200 regardless of whether the request succeeded. For JSON-RPC 2.0 notifications, HTTP 204 will be returned.

2.2.1 CSRF protection

Most Transmission RPC servers require a X-Transmission-Session-Id header to be sent with requests, to prevent CSRF attacks.

When your request has the wrong id -- such as when you send your first request, or when the server expires the CSRF token -- the Transmission RPC server will return an HTTP 409 error with the right X-Transmission-Session-Id in its own headers.

So, the correct way to handle a 409 response is to update your X-Transmission-Session-Id and to resend the previous request.

2.2.2 DNS rebinding protection

Additional check is being made on each RPC request to make sure that the client sending the request does so using one of the allowed hostnames by which RPC server is meant to be available.

If host whitelisting is enabled (which is true by default), Transmission inspects the Host: HTTP header value (with port stripped, if any) and matches it to one of the whitelisted names. Regardless of host whitelist content, localhost and localhost. domain names as well as all the IP addresses are always implicitly allowed.

For more information on configuration, see Editing Configuration Files documentation for rpc_host_whitelist_enabled and rpc_host_whitelist keys.

2.2.3 Authentication

Enabling authentication is an optional security feature that can be enabled on Transmission RPC servers. Authentication occurs by method of HTTP Basic Access Authentication.

If authentication is enabled, Transmission inspects the Authorization: HTTP header value to validate the credentials of the request. The value of this HTTP header is expected to be Basic <b64 credentials>, where is equal to a base64 encoded string of the username and password (respectively), separated by a colon.

3 Torrent requests

3.1 Torrent action requests

Method name	libtransmission function	Description
torrent_start	tr_torrentStart	start torrent
torrent_start_now	tr_torrentStartNow	start torrent disregarding queue position
torrent_stop	tr_torrentStop	stop torrent
torrent_verify	tr_torrentVerify	verify torrent
torrent_reannounce	tr_torrentManualUpdate	re-announce to trackers now

Request parameters: ids, which specifies which torrents to use. All torrents are used if the ids parameter is omitted.

ids should be one of the following:

1. an integer referring to a torrent id
2. a list of torrent id numbers, SHA1 hash strings, or both
3. a string, recently_active, for recently-active torrents

Note that integer torrent ids are not stable across Transmission daemon restarts. Use torrent hashes if you need stable ids.

Response parameters: none

3.2 Torrent mutator: torrent_set

Method name: torrent_set

Request parameters:

Key	Value Type	Value Description
bandwidth_priority	number	this torrent's bandwidth tr_priority_t
download_limit	number	maximum download speed (kB/s)
download_limited	boolean	true if download_limit is honored
files_unwanted	array	indices of file(s) to not download
files_wanted	array	indices of file(s) to download
group	string	The name of this torrent's bandwidth group
honors_session_limits	boolean	true if session upload limits are honored
ids	array	torrent list, as described in 3.1
labels	array	array of string labels
location	string	new location of the torrent's content
peer_limit	number	maximum number of peers
priority_high	array	indices of high-priority file(s)
priority_low	array	indices of low-priority file(s)
priority_normal	array	indices of normal-priority file(s)
queue_position	number	position of this torrent in its queue [0...n)
seed_idle_limit	number	torrent-level number of minutes of seeding inactivity
seed_idle_mode	number	which seeding inactivity to use. See tr_idlelimit
seed_ratio_limit	double	torrent-level seeding ratio
seed_ratio_mode	number	which ratio to use. See tr_ratiolimit
sequential_download	boolean	download torrent pieces sequentially
sequential_download_from_piece	number	download from a specific piece when sequential download is enabled
tracker_add	array	DEPRECATED use tracker_list instead
tracker_list	string	string of announce URLs, one per line, and a blank line between tiers.
tracker_remove	array	DEPRECATED use tracker_list instead
tracker_replace	array	DEPRECATED use tracker_list instead
upload_limit	number	maximum upload speed (kB/s)
upload_limited	boolean	true if upload_limit is honored

Just as an empty ids value is shorthand for "all ids", using an empty array for files_wanted, files_unwanted, priority_high, priority_low, or priority_normal is shorthand for saying "all files".

Response parameters: none

3.3 Torrent accessor: torrent_get

Method name: torrent_get.

Request parameters:

1. An optional ids array as described in 3.1.
2. A required fields array of keys. (see list below)
3. An optional format string specifying how to format the torrents response field. Allowed values are objects (default) and table. (see "Response parameters" below)

Response parameters:

1. A torrents array.

   If the format request was objects (default), torrents will be an array of objects, each of which contains the key/value pairs matching the request's fields arg. This was the only format before Transmission 3 and has some obvious programmer conveniences, such as parsing directly into Javascript objects.

   If the format was table, then torrents will be an array of arrays. The first row holds the keys and each remaining row holds a torrent's values for those keys. This format is more efficient in terms of JSON generation and JSON parsing.

2. If the request's ids field was recently_active, a removed array of torrent-id numbers of recently-removed torrents.

Note: For more information on what these fields mean, see the comments in libtransmission/transmission.h. The 'source' column here corresponds to the data structure there.

Key	Value Type	transmission.h source
activity_date	number	tr_stat
added_date	number	tr_stat
availability	array (see below)	tr_torrentAvailability()
bandwidth_priority	number	tr_priority_t
bytes_completed	array (see below)	n/a
comment	string	tr_torrent_view
corrupt_ever	number	tr_stat
creator	string	tr_torrent_view
date_created	number	tr_torrent_view
desired_available	number	tr_stat
done_date	number	tr_stat
download_dir	string	tr_torrent
downloaded_ever	integer	tr_stat
download_limit	integer	tr_torrent
download_limited	boolean	tr_torrent
edit_date	number	tr_stat
error	number	tr_stat
error_string	string	tr_stat
eta	number	tr_stat
eta_idle	number	tr_stat
file_count	number	tr_info
files	array (see below)	n/a
file_stats	array (see below)	n/a
group	string	n/a
hash_string	string	tr_torrent_view
have_unchecked	number	tr_stat
have_valid	number	tr_stat
honors_session_limits	boolean	tr_torrent
id	integer	tr_torrent
is_finished	boolean	tr_stat
is_private	boolean	tr_torrent
is_stalled	boolean	tr_stat
labels	array of strings	tr_torrent
left_until_done	number	tr_stat
magnet_link	string	n/a
manual_announce_time	number	DEPRECATED don't use it, it never worked
max_connected_peers	number	tr_torrent
metadata_percent_complete	double	tr_stat
name	string	tr_torrent_view
peer_limit	number	tr_torrent
peers	array (see below)	n/a
peers_connected	number	tr_stat
peers_from	object (see below)	n/a
peers_getting_from_us	number	tr_stat
peers_sending_to_us	number	tr_stat
percent_complete	double	tr_stat
percent_done	double	tr_stat
pieces	string (see below)	tr_torrent
piece_count	number	tr_torrent_view
piece_size	number	tr_torrent_view
priorities	array (see below)	n/a
primary_mime_type	string	tr_torrent
queue_position	number	tr_stat
rate_download (B/s)	number	tr_stat
rate_upload (B/s)	number	tr_stat
recheck_progress	double	tr_stat
seconds_downloading	number	tr_stat
seconds_seeding	number	tr_stat
seed_idle_limit	number	tr_torrent
seed_idle_mode	number	tr_inactivelimit
seed_ratio_limit	double	tr_torrent
seed_ratio_mode	number	tr_ratiolimit
sequential_download	boolean	tr_torrent
sequential_download_from_piece	number	tr_torrent
size_when_done	number	tr_stat
start_date	number	tr_stat
status	number (see below)	tr_stat
torrent_file	string	tr_info
total_size	number	tr_torrent_view
trackers	array (see below)	n/a
tracker_list	string	string of announce URLs, one per line, with a blank line between tiers
tracker_stats	array (see below)	n/a
uploaded_ever	integer	tr_stat
upload_limit	integer	tr_torrent
upload_limited	boolean	tr_torrent
upload_ratio	double	tr_stat
wanted	array (see below)	n/a
webseeds	array of strings	DEPRECATED tr_tracker_view
webseeds_ex	array (see below)	n/a
webseeds_sending_to_us	number	tr_stat

availability: An array of piece_count numbers representing the number of connected peers that have each piece, or -1 if we already have the piece ourselves.

bytes_completed: An array of tr_info.filecount numbers. Each is the completed bytes for the corresponding file.

files: array of objects, each containing:

Key	Value Type	transmission.h source
bytes_completed	number	tr_file_view
length	number	tr_file_view
name	string	tr_file_view
begin_piece	number	tr_file_view
end_piece	number	tr_file_view

Files are returned in the order they are laid out in the torrent. References to "file indices" throughout this specification should be interpreted as the position of the file within this ordering, with the first file bearing index 0.

file_stats: a file's non-constant properties. An array of tr_info.filecount objects, in the same order as files, each containing:

Key	Value Type	transmission.h source
bytes_completed	number	tr_file_view
wanted	boolean	tr_file_view
priority	number	tr_file_view

peers: an array of objects, each containing:

Key	Value Type	transmission.h source
address	string	tr_peer_stat
bytes_to_client	number	tr_peer_stat
bytes_to_peer	number	tr_peer_stat
client_is_choked	boolean	tr_peer_stat
client_is_interested	boolean	tr_peer_stat
client_name	string	tr_peer_stat
flag_str	string	tr_peer_stat
is_downloading_from	boolean	tr_peer_stat
is_encrypted	boolean	tr_peer_stat
is_incoming	boolean	tr_peer_stat
is_uploading_to	boolean	tr_peer_stat
is_utp	boolean	tr_peer_stat
peer_id	string	tr_peer_stat
peer_is_choked	boolean	tr_peer_stat
peer_is_interested	boolean	tr_peer_stat
port	number	tr_peer_stat
progress	double	tr_peer_stat
rate_to_client (B/s)	number	tr_peer_stat
rate_to_peer (B/s)	number	tr_peer_stat

peers_from: an object containing:

Key	Value Type	transmission.h source
from_cache	number	tr_stat
from_dht	number	tr_stat
from_incoming	number	tr_stat
from_lpd	number	tr_stat
from_ltep	number	tr_stat
from_pex	number	tr_stat
from_tracker	number	tr_stat

pieces: A bitfield holding piece_count flags which are set to 'true' if we have the piece matching that position. JSON doesn't allow raw binary data, so this is a base64-encoded string. (Source: tr_torrent)

priorities: An array of tr_torrentFileCount() numbers. Each is the tr_priority_t mode for the corresponding file.

status: A number between 0 and 6, where:

Value	Meaning
0	Torrent is stopped
1	Torrent is queued to verify local data
2	Torrent is verifying local data
3	Torrent is queued to download
4	Torrent is downloading
5	Torrent is queued to seed
6	Torrent is seeding

trackers: array of objects, each containing:

Key	Value Type	transmission.h source
announce	string	tr_tracker_view
id	integer	tr_tracker_view
scrape	string	tr_tracker_view
sitename	string	tr_tracker_view
tier	number	tr_tracker_view

tracker_stats: array of objects, each containing:

Key	Value Type	transmission.h source
announce	string	tr_tracker_view
announce_state	number	tr_tracker_view
download_count	number	tr_tracker_view
downloader_count	number	tr_tracker_view
has_announced	boolean	tr_tracker_view
has_scraped	boolean	tr_tracker_view
host	string	tr_tracker_view
id	integer	tr_tracker_view
is_backup	boolean	tr_tracker_view
last_announce_peer_count	number	tr_tracker_view
last_announce_result	string	tr_tracker_view
last_announce_start_time	number	tr_tracker_view
last_announce_succeeded	boolean	tr_tracker_view
last_announce_time	number	tr_tracker_view
last_announce_timed_out	boolean	tr_tracker_view
last_scrape_result	string	tr_tracker_view
last_scrape_start_time	number	tr_tracker_view
last_scrape_succeeded	boolean	tr_tracker_view
last_scrape_time	number	tr_tracker_view
last_scrape_timed_out	boolean	tr_tracker_view
leecher_count	number	tr_tracker_view
next_announce_time	number	tr_tracker_view
next_scrape_time	number	tr_tracker_view
scrape	string	tr_tracker_view
scrape_state	number	tr_tracker_view
seeder_count	number	tr_tracker_view
sitename	string	tr_tracker_view
tier	number	tr_tracker_view

webseeds_ex: array of objects, each containing:

Key	Value Type	transmission.h source
url	string	tr_webseed_view
is_downloading	boolean	tr_webseed_view
download_bytes_per_second	number	tr_webseed_view

wanted: An array of tr_torrentFileCount() booleans, true if the corresponding file is to be downloaded. (Source: tr_file_view)

Note: For backwards compatibility, in the old bespoke API, wanted is serialized as an array of 0 or 1 that should be treated as booleans.

Example:

Say we want to get the name and total size of torrents #7 and #10.

Request:

{
   "jsonrpc": "2.0",
   "params": {
       "fields": [ "id", "name", "total_size" ],
       "ids": [ 7, 10 ]
   },
   "method": "torrent_get",
   "id": 39693
}

Response:

{
   "jsonrpc": "2.0",
   "result": {
      "torrents": [
         {
             "id": 10,
             "name": "Fedora x86_64 DVD",
             "total_size": 34983493932
         },
         {
             "id": 7,
             "name": "Ubuntu x86_64 DVD",
             "total_size": 9923890123
         }
      ]
   },
   "id": 39693
}

3.4 Adding a torrent

Method name: torrent_add

Request parameters:

Key	Value Type	Description
cookies	string	pointer to a string of one or more cookies.
download_dir	string	path to download the torrent to
filename	string	filename or URL of the .torrent file
labels	array	array of string labels
metainfo	string	base64-encoded .torrent content
paused	boolean	if true, don't start the torrent
peer_limit	number	maximum number of peers
bandwidth_priority	number	torrent's bandwidth tr_priority_t
files_wanted	array	indices of file(s) to download
files_unwanted	array	indices of file(s) to not download
priority_high	array	indices of high-priority file(s)
priority_low	array	indices of low-priority file(s)
priority_normal	array	indices of normal-priority file(s)
sequential_download	boolean	download torrent pieces sequentially
sequential_download_from_piece	number	download from a specific piece when sequential download is enabled

Either filename or metainfo must be included. All other parameters are optional.

The format of the cookies should be NAME=CONTENTS, where NAME is the cookie name and CONTENTS is what the cookie should contain. Set multiple cookies like this: name1=content1; name2=content2; etc. See libcurl documentation for more information.

Response parameters:

• On success, a torrent_added object in the form of one of 3.3's torrent objects with the fields for id, name, and hash_string.

• When attempting to add a duplicate torrent, a torrent_duplicate object in the same form is returned, but the response's result value is still success.

3.5 Removing a torrent

Method name: torrent_remove

Key	Value Type	Description
ids	array	torrent list, as described in 3.1
delete_local_data	boolean	delete local data. (default: false)

Response parameters: none

3.6 Moving a torrent

Method name: torrent_set_location

Request parameters:

Key	Value Type	Description
ids	array	torrent list, as described in 3.1
location	string	the new torrent location
move	boolean	if true, move from previous location. otherwise, search location for files (default: false)

Response parameters: none

3.7 Renaming a torrent's path

Method name: torrent_rename_path

For more information on the use of this function, see the transmission.h documentation of tr_torrentRenamePath(). In particular, note that if this call succeeds you'll want to update the torrent's files and name field with torrent_get.

Request parameters: