1. Introduction This document describes a protocol for interacting with Transmission sessions remotely. 1.1 Terminology The JSON terminology in RFC 4627 is used. In benc terms, a JSON "array" is equivalent to a benc list, a JSON "object" is equivalent to a benc dictionary, and a JSON object's "keys" are the dictionary's string keys. 2. Message Format Messages are formatted in a subset of JSON easily represented as bencoded data. Arrays, objects, strings, and whole numbers all have one-to-one mappings between JSON and benc. Booleans and floating-point numbers are also used in the JSON messages. Those two types aren't native to benc, so they're encoded this way: Booleans are encoded as numbers where 0 is false and 1 is true. Floating-point numbers are represented as strings. Messages are formatted as objects. There are two types: requests (described in 2.1) and responses (described in 2.2). All text MUST be UTF-8 encoded. 2.1. Requests Requests support three keys: (1) A required "method" string telling the name of the method to invoke (2) An optional "arguments" object of key/value pairs (3) An optional "tag" number used by clients to track responses. If provided by a request, the response MUST include the same tag. 2.2. Responses Reponses support three keys: (1) A required "result" string whose value MUST be "success" on success, or an error string on failure. (2) An optional "arguments" object of key/value pairs (3) An optional "tag" number as described in 2.1. 2.3. 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. In addition to POSTing, there's also a simple notation for sending requests in the query portion of a URL. This is not as robust, but can be useful for debugging and simple tasks. The notation works as follows: (1) Any key not "tag" or "method" is treated as an argument. (2) The "arguments" key isn't needed, since data isn't nested. (3) If the value in a key/value pair can be parsed as a number, then it is. Otherwise if it can be parsed as an array of numbers, then it is. Otherwise, it's parsed as a string. Examples: ?method=torrent-start&ids=1,2 ?method=session-set&speed-limit-down=50&speed-limit-down-enabled=1 3. Torrent Requests 3.1. Torrent Action Requests Method name | libtransmission function ---------------------+------------------------------------------------- "torrent-start" | tr_torrentStart "torrent-stop" | tr_torrentStop "torrent-verify" | tr_torrentVerify "torrent-reannounce" | tr_torrentManualUpdate ("ask tracker for more peers") Request arguments: "ids", which specifies which torrents to use. All torrents are used if the "ids" argument 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 Response arguments: none 3.2. Torrent Mutators Method name: "torrent-set" Request arguments: string | value type & description ----------------------------------+------------------------------------------------- "downloadLimit" | number maximum download speed (in K/s) "downloadLimited" | 'boolean' true if "downloadLimit" is honored "files-wanted" | array indices of file(s) to download "files-unwanted" | array indices of file(s) to not download "honorsSessionLimits" | 'boolean' true if session upload limits are honored "ids" | array torrent list, as described in 3.1 "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) "seedRatioLimit" | 'double' session seeding ratio "seedRatioLimited" | 'boolean' true if "seedRatioLimit" is honored "uploadLimit" | number maximum upload speed (in K/s) "uploadLimited" | 'boolean' true if "uploadLimit" 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 arguments: none 3.3. Torrent Accessors Method name: "torrent-get". Request arguments: (1) An opional "ids" array as described in 3.1. (2) A required "fields" array of keys. (see list below) Response arguments: (1) A "torrents" array of objects, each of which contains the key/value pairs matching the request's "fields" argument. key | type | source --------------------------------+-----------------------------+--------- activityDate | number | tr_stat addedDate | number | tr_stat announceResponse | string | tr_stat announceURL | string | tr_stat comment | string | tr_info corruptEver | number | tr_stat creator | string | tr_info dateCreated | number | tr_info desiredAvailable | number | tr_stat doneDate | number | tr_stat downloadDir | string | tr_torrent downloadedEver | number | tr_stat downloaders | number | tr_stat downloadLimit | number | tr_torrent downloadLimited | 'boolean' | tr_torrent error | number | tr_stat errorString | number | tr_stat eta | number | tr_stat files | array (see below) | n/a hashString | string | tr_info haveUnchecked | number | tr_stat haveValid | number | tr_stat honorsSessionLimits | 'boolean' | tr_torrent id | number | tr_torrent isPrivate | 'boolean' | tr_torrent lastAnnounceTime | number | tr_stat lastScrapeTime | number | tr_stat leechers | number | tr_stat leftUntilDone | number | tr_stat manualAnnounceTime | number | tr_stat maxConnectedPeers | number | tr_torrent name | string | tr_info nextAnnounceTime | number | tr_stat nextScrapeTime | number | tr_stat peer-limit | number | tr_torrent peers | array (see below) | n/a peersConnected | number | tr_stat peersFrom | object (see below) | n/a peersGettingFromUs | number | tr_stat peersKnown | number | tr_stat peersSendingToUs | number | tr_stat percentDone | 'double' | tr_stat pieces | string (see below) | tr_torrent pieceCount | tnumber | tr_info pieceSize | tnumber | tr_info priorities | array (see below) | n/a ratio | 'double' | tr_stat rateDownload (B/s) | number | tr_stat rateUpload (B/s) | number | tr_stat recheckProgress | 'double' | tr_stat scrapeResponse | string | tr_stat scrapeURL | string | tr_stat seeders | number | tr_stat seedRatioLimit | 'double' | tr_torrent seedRatioMode | number | tr_ratiolimit sizeWhenDone | number | tr_stat startDate | number | tr_stat status | number | tr_stat swarmSpeed (K/s) | number | tr_stat timesCompleted | number | tr_stat trackers | array (see below) | n/a totalSize | number | tr_info uploadedEver | number | tr_stat uploadLimit | number | tr_torrent uploadLimited | 'boolean' | tr_torrent uploadRatio | 'double' | tr_stat wanted | array (see below) | n/a webseeds | array (see below) | n/a webseedsSendingToUs | number | tr_stat | | | | -----------------------+--------+-----------------------------+ files | array of objects, each containing: | +-------------------------+------------+ | key | type | | bytesCompleted | number | tr_torrent | length | number | tr_info | name | string | tr_info -----------------------+--------------------------------------+ peers | array of objects, each containing: | +-------------------------+------------+ | address | string | tr_peer_stat | clientName | string | tr_peer_stat | clientIsChoked | 'boolean' | tr_peer_stat | clientIsInterested | 'boolean' | tr_peer_stat | isDownloadingFrom | 'boolean' | tr_peer_stat | isEncrypted | 'boolean' | tr_peer_stat | isIncoming | 'boolean' | tr_peer_stat | isUploadingTo | 'boolean' | tr_peer_stat | peerIsChoked | 'boolean' | tr_peer_stat | peerIsInterested | 'boolean' | tr_peer_stat | port | number | tr_peer_stat | progress | 'double' | tr_peer_stat | rateToClient (B/s) | number | tr_peer_stat | rateToPeer (B/s) | number | tr_peer_stat -----------------------+--------------------------------------+ peersFrom | an object containing: | +-------------------------+------------+ | fromCache | number | tr_stat | fromIncoming | number | tr_stat | fromPex | number | tr_stat | fromTracker | number | tr_stat -----------------------+--------------------------------------+ pieces | A bitfield holding pieceCount flags | tr_torrent | 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. | -----------------------+--------------------------------------+ priorities | an array of tr_info.filecount | tr_info | numbers. each is the tr_priority_t | | mode for the corresponding file. | -----------------------+--------------------------------------+ trackers | array of objects, each containing: | +-------------------------+------------+ | announce | string | tr_info | scrape | string | tr_info | tier | number | tr_info -----------------------+--------------------------------------+ wanted | an array of tr_info.fileCount | tr_info | 'booleans' true if the corresponding | | file is to be downloaded. | -----------------------+--------------------------------------+ webseeds | an array of strings: | +-------------------------+------------+ | webseed | string | tr_info +-------------------------+------------+ Example: Say we want to get the name and total size of torrents #7 and #10. Request: { "arguments": { "fields": [ "id", "name", "totalSize" ], "ids": [ 7, 10 ] }, "method": "torrent-get", "tag": 39693 } Response: { "arguments": { "torrents": [ { "id": 10, "name": "Fedora x86_64 DVD", "totalSize", 34983493932, }, { "id": 7, "name": "Ubuntu x86_64 DVD", "totalSize", 9923890123, } ] }, "result": "success", "tag": 39693 } 3.4. Adding a Torrent Method name: "torrent-add" Request arguments: key | value type & description -------------------+------------------------------------------------- "download-dir" | string path to download the torrent to "filename" | string filename or URL of the .torrent file "metainfo" | string base64-encoded .torrent content "paused" | 'boolean' if true, don't start the torrent "peer-limit" | number maximum number of peers Either "filename" OR "metainfo" MUST be included. All other arguments are optional. Response arguments: on success, a "torrent-added" object in the form of one of 3.3's tr_info objects with the fields for id, name, and hashString. 3.5. Removing a Torrent Method name: "torrent-remove" Request arguments: string | value type & description ---------------------------+------------------------------------------------- "ids" | array torrent list, as described in 3.1 "delete-local-data" | 'boolean' delete local data. (default: false) Response arguments: none 4. Session Requests 4.1. Session Arguments string | value type & description ---------------------------+------------------------------------------------- "alt-speed-down" | number max global download speed (in K/s) "alt-speed-enabled" | 'boolean' true means use the alt speeds "alt-speed-time-begin" | number when to turn on alt speeds (units: minutes after midnight) "alt-speed-time-enabled" | 'boolean' true means the scheduled on/off times are used "alt-speed-time-end" | number when to turn off alt speeds (units: same) "alt-speed-up" | number max global upload speed (in K/s) "blocklist-enabled" | 'boolean' true means enabled "blocklist-size" | number number of rules in the blocklist "encryption" | string "required", "preferred", "tolerated" "download-dir" | string default path to download torrents "peer-limit-global" | number maximum global number of peers "peer-limit-per-torrent" | number maximum global number of peers "pex-enabled" | 'boolean' true means allow pex in public torrents "peer-port" | number port number "port-forwarding-enabled" | 'boolean' true means enabled "rpc-version" | number the current RPC API version "rpc-version-minimum" | number the minimum RPC API version supported "speed-limit-down" | number max global download speed (in K/s) "speed-limit-down-enabled" | 'boolean' true means enabled "speed-limit-up" | number max global upload speed (in K/s) "speed-limit-up-enabled" | 'boolean' true means enabled "version" | string long version string "$version ($revision)" "rpc-version" indicates the RPC interface version supported by the RPC server. It is incremented when a new version of Transmission changes the RPC interface. "rpc-version-minimum" indicates the oldest API supported by the RPC server. It is changes when a new version of Transmission changes the RPC interface in a way that is not backwards compatible. There are no plans for this to be common behavior. 4.1.1. Mutators Method name: "session-set" Request arguments: one or more of 4.1's arguments, except: "blocklist-size", "rpc-version", "rpc-version-minimum", and "version" Response arguments: none 4.1.2. Accessors Method name: "session-get" Request arguments: none Response arguments: all of 4.1's arguments 4.2. Session Statistics Method name: "session-stats" Request arguments: none Response arguments: string | value type ---------------------------+------------------------------------------------- "activeTorrentCount" | number "downloadSpeed" | number "pausedTorrentCount" | number "torrentCount" | number "uploadSpeed" | number ---------------------------+-------------------------------+ "cumulative-stats" | object, containing: | +------------------+------------+ | uploadedBytes | number | tr_session_stats | downloadedBytes | number | tr_session_stats | filesAdded | number | tr_session_stats | sessionCount | number | tr_session_stats | secondsActive | number | tr_session_stats ---------------------------+-------------------------------+ "current-stats" | object, containing: | +------------------+------------+ | uploadedBytes | number | tr_session_stats | downloadedBytes | number | tr_session_stats | filesAdded | number | tr_session_stats | sessionCount | number | tr_session_stats | secondsActive | number | tr_session_stats 5.0. Protocol Versions The following changes have been made to the RPC interface: RPC | Release | Backwards | | Vers. | Version | Compat? | Method | Description ------+---------+-----------+----------------+------------------------------- 1 | 1.30 | n/a | n/a | Initial version ------+---------+-----------+----------------+------------------------------- 2 | 1.34 | yes | torrent-get | new arg "peers" ------+---------+-----------+----------------+------------------------------- 3 | 1.41 | yes | torrent-get | added "port" to "peers" | | yes | torrent-get | new arg "downloaders" | | yes | session-get | new arg "version" | | yes | torrent-remove | new method ------+---------+-----------+----------------+------------------------------- 4 | 1.50 | yes | session-get | new arg "rpc-version" | | yes | session-get | new arg "rpc-version-minimum" | | yes | session-stats | added "cumulative-stats" | | yes | session-stats | added "current-stats" | | yes | torrent-get | new arg "downloadDir" ------+---------+-----------+----------------+------------------------------- 6 | 1.60 | yes | torrent-get | new arg "pieces" | | yes | torrent-set | new arg "ratio" | | yes | torrent-set | new arg "downloadLimited" | | yes | torrent-set | new arg "uploadLimited" | | yes | torrent-set | new arg "honorsSessionLimits" | | yes | session-get | new arg "seedRatioLimit" | | yes | session-get | new arg "seedRatioLimited" | | yes | session-get | new arg "alt-speed-enabled" | | yes | session-get | new arg "alt-speed-time-enabled" | | yes | session-get | new arg "alt-speed-up" | | yes | session-get | new arg "alt-speed-down" | | yes | session-get | new arg "alt-speed-begin" | | yes | session-get | new arg "alt-speed-end" | | yes | session-get | new arg "blocklist-enabled" | | yes | session-get | new arg "blocklist-size" | | yes | session-get | new arg "peer-limit-per-torrent" | | yes | torrent-get | new arg "seedRatioLimit" | | yes | torrent-get | new arg "seedRatioMode" | | yes | torrent-get | new ids option "recently-active" | | yes | torrent-get | new ids option "percentDone" | | yes | | new method "torrent-reannounce" | | NO | torrent-get | removed arg "downloadLimitMode" | | NO | torrent-get | removed arg "uploadLimitMode" | | NO | session-get | renamed "pex-allowed" to "pex-enabled" | | NO | session-get | renamed "port" to "peer-port" | | NO | session-get | renamed "peer-limit" to "peer-limit-global" ------+---------+-----------+----------------+-------------------------------