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:

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

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:

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.

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:

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:

peers: an array of objects, each containing:

peers_from: an object containing:

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:

trackers: array of objects, each containing:

tracker_stats: array of objects, each containing:

webseeds_ex: array of objects, each containing:

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:

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

Response parameters: none

3.6 Moving a torrent

Method name: torrent_set_location

Request parameters:

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:

Response parameters: path, name, and id, holding the torrent ID integer

4 Session requests

4.1 Session parameters

units: an object containing:

4.1.1 Mutators

Method name: session_set

Request parameters: the mutable properties from 4.1's parameters, i.e. all of them except:

• blocklist_size
• config_dir
• rpc_version_minimum,
• rpc_version_semver
• rpc_version
• session_id
• tcp_enabled
• units
• version

Response parameters: none

4.1.2 Accessors

Method name: session_get

Request parameters: an optional fields array of keys (see 4.1)

Response parameters: key/value pairs matching the request's fields parameter if present, or all supported fields (see 4.1) otherwise.

4.2 Session statistics

Method name: session_stats

Request parameters: none

Response parameters:

A stats object contains:

4.3 Blocklist

Method name: blocklist_update

Request parameters: none

Response parameters: a number blocklist_size

4.4 Port checking

This method tests to see if your incoming peer port is accessible from the outside world.

Method name: port_test

Request parameters: an optional parameter ip_protocol. ip_protocol is a string specifying the IP protocol version to be used for the port test. Set to ipv4 to check IPv4, or set to ipv6 to check IPv6. For backwards compatibility, it is allowed to omit this parameter to get the behaviour before Transmission 4.1.0, which is to check whichever IP protocol the OS happened to use to connect to our port test service, frankly not very useful.

Response parameters:

4.5 Session shutdown

This method tells the Transmission session to shut down.

Method name: session_close

Request parameters: none

Response parameters: none

4.6 Queue movement requests

Request parameters:

Response parameters: none

4.7 Free space

This method tests how much free space is available in a client-specified folder.

Method name: free_space

Request parameters:

Response parameters:

4.8 Bandwidth groups

4.8.1 Bandwidth group mutator: group_set

Method name: group_set

Request parameters:

Response parameters: none

4.8.2 Bandwidth group accessor: group_get

Method name: group_get

Request parameters: An optional parameter name. name is either a string naming the bandwidth group, or a list of such strings. If name is omitted, all bandwidth groups are used.

Response parameters:

A bandwidth group description object has:

5 Protocol versions

This section lists the changes that have been made to the RPC protocol.

There are two ways to check for API compatibility. Since most developers know semver, session_get's rpc_version_semver is the recommended way. That value is a semver-compatible string of the RPC protocol version number.

DEPRECATED Since Transmission predates the semver 1.0 spec, the previous scheme was for the RPC version to be a whole number and to increment it whenever a change was made. That is session_get's rpc_version. rpc_version_minimum lists the oldest version that is compatible with the current version; i.e. an app coded to use rpc_version_minimum would still work on a Transmission release running rpc_version.

Starting from rpc-version-semver 6.0.0, Transmission returns the RPC version in an HTTP header X-Transmission-Rpc-Version: {rpc_version_semver} in the CSRF HTTP 409 response. This is so that clients supporting both JSON-RPC and the old bespoke API can determine which scheme to use without making any extra requests. Example: X-Transmission-Rpc-Version: 6.0.0

Breaking changes are denoted with a :bomb: emoji.

Transmission 1.30 (rpc-version-semver 1.0.0, rpc-version: 1)

Initial revision.

Transmission 1.40 (rpc-version-semver 1.1.0, rpc-version: 2)

Transmission 1.41 (rpc-version-semver 1.2.0, rpc-version: 3)

Transmission 1.50 (rpc-version-semver 1.3.0, rpc-version: 4)

Transmission 1.60 (rpc-version-semver 2.0.0, rpc-version: 5)

Transmission 1.70 (rpc-version-semver 2.1.0, rpc-version: 6)

Transmission 1.80 (rpc-version-semver 3.0.0, rpc-version: 7)

…(truncated)