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.

   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
   ---------------------------+-------------------------------+
   "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"
         |         |           | 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"
         |         |           | session-stats  | added "cumulative-stats"
         |         |           | session-stats  | added "current-stats"
         |         |           | torrent-get    | new arg "downloadDir"
   ------+---------+-----------+----------------+-------------------------------