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 numbers.
   Booleans are represented as numbers where 0 is false and 1 is true.

   Messages are formatted as objects.  There are two types:
   requests (described in 2.1) and responses (described in 2.2).

2.1.  Requests

   Requests supports 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" integer 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" integer as described in 2.1.

2.3.  Transport Mechanism

   POSTing a JSON-encoded request is the preferred way of communicating
   with the Transmission 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 integers, 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 Information Requests

   Method name: "torrent-info".

   The request supports four arguments:

   (1) An optional "ids" array as described in section 3.1.
   (2) A required "fields" number as described in the table below.
   (3) An optional "sort" string whose value should be one of
       "activity", "age", "id", "name", "progress", "ratio", "state", "tracker".
       The default value is "id".
   (4) An optional "sort-ascending" 'boolean'.
       This is only used if "sort-method" is supplied.
       Its default value is 'true'.
   (5) An optional "filter" string whose value may be one of
       "active", "all", "downloading", "paused", "seeding".
       The default value is "all".

   The respons supports two arguments:

   (1) A required "fields" number identical to the request's
   (2) A "torrent-info" list of objects, each of which contains the
       response names described in the table below.

   field and          | response | response               | source
   numeric value      | type     | name                   | 
   -------------------+----------+------------------------+-------------
   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             | tr_stat
                      | 'double' | uploadRatio            | tr_stat
                      | number   | webseedsSendingToUs    | tr_stat
   -------------------+----------+------------------------+-------------
   announce, 2        | string   | announceResponse       | tr_stat
                      | string   | announceURL            | tr_stat
                      | string   | lastAnnounceTime       | tr_stat
                      | string   | manualAnnounceTime     | tr_stat
                      | string   | 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
   -------------------+----------+------------------------+-------------
   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
   -------------------+----------+------------------------+-------------
   scrape, 512        | number   | lastScrapeTime         | tr_stat
                      | number   | nextScrapeTime         | tr_stat
                      | string   | scrapeResponse         | tr_stat
                      | string   | scrapeURL              | tr_stat
   -------------------+----------+------------------------+-------------
   size, 1024         | 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
   2048               | number   | peersKnown             | tr_stat
                      | number   | seeders                | tr_stat
                      | number   | timesCompleted         | tr_stat
   -------------------+----------+--------------------------------------
   trackers, 4096     | array    | trackers
                      +----------+-------------------------------------- 
                      | trackers is an array of objects that contain:
                      +----------+------------------------+------------- 
                      | string   | announce               | tr_info
                      | string   | scrape                 | tr_info
                      | number   | tier                   | tr_info
   -------------------+----------+------------------------+-------------
   webseeds, 8192     | object   | webseeds
                      +----------+-------------------------------------- 
                      | webseeds contains:
                      +----------+------------------------+------------- 
                      | an array of weseed URL strings    | tr_info
   -------------------+----------+------------------------+-------------


   Example:

   Say we want to get the name and total size torrents 7 and 10.
   name is in the "id" section (32) and total size is in "size" (1024),
   so the "fields" argument will be 32 + 1024 == 1056.

   Request: 

      {
         "arguments": {
             "fields": 1056,
             "ids": [ 7, 10 ],
             "sort-method": "name"
         }
         "method": "torrent-info",
         "tag": 39693
      }


   Response:

      {
         "arguments": {
            "fields": 1056,
            "torrent-info": [ 
               { 
                   "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.3.  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"       | int       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.4.  Other Torrent Settings

   Common arguments:

   string                     | value type & description
   ---------------------------+-------------------------------------------------
   "peer-limit"               | int       maximum number of peers
   "speed-limit-down"         | int       maximum download speed (in KiB/s)
   "speed-limit-down-enabled" | boolean   true if the download speed is limited
   "speed-limit-up"           | int       maximum upload speed (in KiB/s)
   "speed-limit-up-enabled"   | boolean   true if the upload speed is limited

3.4.1.  Mutators

   Method name: "torrent-set"
   Request arguments: 3.1's "ids", plus one or more of 3.6's arguments
   Response arguments: none
                      

3.5  File Priorities

   Common arguments:

   string             | value type & description
   -------------------+-------------------------------------------------
   "files-wanted"     | array     indices of one or more file to download
   "files-unwanted"   | array     indices of one or more file to not download
   "priority-high"    | array     indices of one or more high-priority files
   "priority-low"     | array     indices of one or more low-priority files
   "priority-normal"  | array     indices of one or more normal-priority files

3.5.1.  Mutators

    Method name: "torrent-set-priorities"
    Request arguments: 3.1's "ids", plus one or more of 3.7's arguments
    Response arguments: none

3.5.2.  Accessors

    Method name: "torrent-get-priorities"
    Request arguments: none
    Response arguments: A "torrents" list of objects containing all
                        of 3.7's arguments plus the torrent's "id" int.
   
4.   Session Status Requests

4.1.  Session Arguments

   string                     | value type & description
   ---------------------------+-------------------------------------------------
   "encryption"               | string   "required", "preferred", "tolerated"
   "download-dir"             | string   default path to download torrents
   "peer-limit"               | int      maximum global number of peers
   "pex-allowed"              | boolean  true means allow pex in public torrents
   "port"                     | int      port number
   "port-forwarding-enabled"  | boolean  true means enabled
   "speed-limit-down"         | int      max global download speed (in KiB/s)
   "speed-limit-down-enabled" | boolean  true means enabled
   "speed-limit-up"           | int      max global upload speed (in KiB/s)
   "speed-limit-up-enabled"   | boolean  true means enabled

4.2.  Mutators

   Method name: "session-set"
   Request arguments: one or more of 4.1's arguments
   Response arguments: none

4.2.  Accessors

   Method name: "session-get"
   Request arguments: none
   Response arguments: all of 4.1's arguments