1. Introduction This document describes a protocol for interacting with Transmission sessions remotely. 1.1 Terminology The JSON terminology in RFC 4627 is used. "array" is equivalent to a benc list; "object" is equivalent to a benc dictionary; and an 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. Booleans are represented 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). 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-remove" | tr_torrentRemove "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 Mutator 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 Response arguments: none 3.3. Torrent Accessors Method name: "torrent-get". Request arguments: string | required? | default | value type & description -------------+-----------+---------+--------------------------------------- "ids" | no | all | array described in 3.1 "fields" | yes | n/a | number bitwise-or'ed field | | | values from the table below Response arguments: (1) A "fields" number identical to the request's (2) A "torrents" array of objects, each of which contains the key/value fields that match the "fields" argument. See the table below for a complete list. "fields" value | response | response | source | value | key | -------------------+----------+------------------------+------------- activity, 1 | number | desiredAvailable | tr_stat | number | eta | tr_stat | number | peersConnected | tr_stat | number | peersGettingFromUs | tr_stat | number | peersSendingToUs | tr_stat | number | rateDownload | tr_stat | number | rateUpload | tr_stat | number | recheckProgress | tr_stat | number | status | tr_stat | number | swarmSpeed (K/s) | tr_stat | 'double' | uploadRatio | tr_stat | number | webseedsSendingToUs | tr_stat -------------------+----------+------------------------+------------- announce, 2 | string | announceResponse | tr_stat | string | announceURL | tr_stat | number | lastAnnounceTime | tr_stat | number | manualAnnounceTime | tr_stat | number | nextAnnounceTime | tr_stat -------------------+----------+------------------------+------------- error, 4 | number | error | tr_stat | number | errorString | tr_stat -------------------+----------+------------------------+------------- files, 8 | array | files +----------+-------------------------------------- | files is an array of objects that contain: +----------+------------------------+------------- | number | length | tr_info | string | name | tr_info -------------------+----------+------------------------+------------- history, 16 | number | activityDate | tr_stat | number | addedDate | tr_stat | number | corruptEver | tr_stat | number | doneDate | tr_stat | number | downloadedEver | tr_stat | number | startDate | tr_stat | number | uploadedEver | tr_stat -------------------+----------+------------------------+------------- id, 32 | number | uniqueId | tr_torrent | string | hashString | tr_info | string | name | tr_info -------------------+----------+------------------------+------------- info, 64 | string | comment | tr_info | string | creator | tr_info | number | dateCreated | tr_info | number | pieceCount | tr_info | number | pieceSize | tr_info | 'boolean'| isPrivate | tr_torrent -------------------+----------+------------------------+------------- limits, 128 | number | downloadLimit | tr_torrent | number | downloadLimitMode | tr_torrent | number | maxConnectedPeers | tr_torrent | number | uploadLimit | tr_torrent | number | uploadLimitMode | tr_torrent -------------------+----------+------------------------+------------- peers, 256 | number | fromCache | tr_stat | number | fromIncoming | tr_stat | number | fromPex | tr_stat | number | fromTracker | tr_stat -------------------+----------+------------------------+------------- priorities, 512 | array | priorities | tr_info | array | wanted | tr_info +----------+-------------------------------------- | priorities is an array of tr_info.fileCount | numbers. Each is the tr_priority_t mode for | the corresponding file. +------------------------------------------------- | wanted is an array of tr_info.fileCount | 'booleans' true if the corresponding file | is to be downloaded. -------------------+----------+------------------------+------------- scrape, 1024 | number | lastScrapeTime | tr_stat | number | nextScrapeTime | tr_stat | string | scrapeResponse | tr_stat | string | scrapeURL | tr_stat -------------------+----------+------------------------+------------- size, 2048 | number | haveUnchecked | tr_stat | number | haveValid | tr_stat | number | leftUntilDone | tr_stat | number | sizeWhenDone | tr_stat | number | totalSize | tr_info -------------------+----------+------------------------+------------- tracker stats, | number | leechers | tr_stat 4096 | number | peersKnown | tr_stat | number | seeders | tr_stat | number | timesCompleted | tr_stat -------------------+----------+-------------------------------------- trackers, 8192 | array | trackers +----------+-------------------------------------- | trackers is an array of objects that contain: +----------+------------------------+------------- | string | announce | tr_info | string | scrape | tr_info | number | tier | tr_info -------------------+----------+------------------------+------------- webseeds, 16384 | array | webseeds +----------+-------------------------------------- | webseeds is an array of strings: +----------+------------------------+------------- | string | webseed URL | tr_info -------------------+----------+------------------------+------------- Example: Say we want to get the name and total size of torrents #7 and #10. name is in the "id" section (32) and total size is in "size" (2048), so the "fields" argument will be 32 + 2048 == 2080. Request: { "arguments": { "fields": 2080, "ids": [ 7, 10 ], "sort-method": "name" } "method": "torrent-get", "tag": 39693 } Response: { "arguments": { "fields": 2080, "torrents": [ { "hashString": "sijioejisoefjiosejfioi", "haveUnchecked", 23023, "haveValid", 27986795145, "leftUntilDone", 0, "name": "Fedora x86_64 DVD", "sizeWhenDone", 34983493932, "totalSize", 34983493932, "uniqueId": 10, } { "hashString": "asdasiofjosejfoasjfiosj", "haveUnchecked", 0, "haveValid", 9923890123, "leftUntilDone", 0, "name": "Ubuntu x86_64 DVD", "sizeWhenDone", 9923890123, "totalSize", 9923890123, "uniqueId": 7, }, ] }, "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 location 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. 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 4.1.1. Mutators Method name: "session-set" Request arguments: one or more of 4.1's arguments 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