transmission/doc/rpc-spec.txt

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         | not defined yet
   -------------------+----------+------------------------+-------------
   peer stats, 512    | number   | fromCache              | tr_stat
                      | number   | fromIncoming           | tr_stat
                      | number   | fromPex                | tr_stat
                      | number   | fromTracker            | tr_stat
   -------------------+----------+------------------------+-------------
   priorities, 1024   | 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, 2048       | number   | lastScrapeTime         | tr_stat
                      | number   | nextScrapeTime         | tr_stat
                      | string   | scrapeResponse         | tr_stat
                      | string   | scrapeURL              | tr_stat
   -------------------+----------+------------------------+-------------
   size, 4096         | 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
   8192               | number   | peersKnown             | tr_stat
                      | number   | seeders                | tr_stat
                      | number   | timesCompleted         | tr_stat
   -------------------+----------+--------------------------------------
   trackers, 16384    | array    | trackers
                      +----------+-------------------------------------- 
                      | trackers is an array of objects that contain:
                      +----------+------------------------+------------- 
                      | string   | announce               | tr_info
                      | string   | scrape                 | tr_info
                      | number   | tier                   | tr_info
   -------------------+----------+------------------------+-------------
   webseeds, 32768    | 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