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; however, a simple notation also exists for sending requests in the query portion of a URL. The URL 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 Request arguments: "ids", a list of torrent id numbers, sha1 hash strings, or both. These are the torrents that the request will be applied to. If "ids" is ommitted, the request is applied to all torrents. Response arguments: none 3.2. Torrent Mutators Method name: "torrent-set" Request arguments: string | value type & description ---------------------------+------------------------------------------------- "files-wanted" | array indices of file(s) to download "files-unwanted" | array indices of file(s) to not download "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) "speed-limit-down" | number maximum download speed (in K/s) "speed-limit-down-enabled" | 'boolean' true if the download speed is limited "speed-limit-up" | number maximum upload speed (in K/s) "speed-limit-up-enabled" | 'boolean' true if the upload speed is limited 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 downloadLimitMode | number | tr_torrent downloadLimit | number | 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 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 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 pieceCount | tnumber | tr_info pieceSize | tnumber | tr_info priorities | array (see below) | n/a 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 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 uploadLimitMode | number | tr_torrent uploadLimit | number | 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 -----------------------+--------------------------------------+ 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" ] }, "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 ---------------------------+------------------------------------------------- "encryption" | string "required", "preferred", "tolerated" "download-dir" | string default path to download torrents "peer-limit" | number maximum global number of peers "pex-allowed" | 'boolean' true means allow pex in public torrents "port" | number port number "port-forwarding-enabled" | 'boolean' true means enabled "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" | number the current RPC API version "rpc-version-minimum" | number the minimum RPC API version supported "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 "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 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" | | | torrent-get | new arg "downloaders" | | | session-get | new arg "version" | | | torrent-remove | new method ------+---------+-----------+----------------+------------------------------- 4 | 1.50 | yes | session-get | new arg "rpc-version" | | | session-get | new arg "rpc-version-minimum" | | | torrent-get | new arg "downloadDir" ------+---------+-----------+----------------+-------------------------------