source: trunk/doc/rpc-spec.txt @ 5868

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;
   an object's "keys" are the dictionary's string keys,
   and an object's "members" are its key/value pairs.

2.  Message Format

   Messages are formatted in a subset of JSON that understands
   arrays, maps, strings, and whole numbers with no exponentials --
   in short, the subset of JSON easily represented as bencoded data.
   Floating-point numbers are represented as strings.
   Booleans are represented as integers where 0 is false and 1 is true.

   Messages are represented as JSON 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 name/value pairs
   (3) An optional "tag" integer used for 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 name/value pairs
   (3) An optional "tag" integer as described in 2.1.

2.3.  Request IPC Notation

   As a convenience, a casual URI notation is supported for requests via the
   query portion of a URI.  The advantage of this is that all current requests
   can be invoked via a very simple http GET request.  The possible future
   disadvantage is that it limits nesting and listing structured requests.

   The URI notation works as follows:
   (1) Any key not "tag" or "method" is assumed to be in "arguments".
   (2) The "arguments" key isn't needed, since data isn't nested.
   (3) If the entire value in a key/value pair can be parsed as an integer,
       it's parsed into a JSON number.
       Otherwise, if the value can be parsed as comma-delimited integers,
       it's parsed into a JSON array of integers.
       Otherwise, the value is treated 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-close"     | tr_torrentClose
   "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 List

   Method name: "torrent-list".

   Request arguments: none.

   Response arguments: "list", an array of objects that contain two keys:
   a torrent's name string, and its unique torrent id. 

3.3.  Torrent Info Requests

   Method name: "torrent-info".

   Request arguments: 3.1's optional "ids" argument.

   Response arguments: "torrent-info", an array of objects based on
   libtransmission's tr_info struct but different in the following ways:
   (1) the torrent's "id" field is added.
   (2) tr_info's "hash" field is omitted.
   (3) tr_info's "pieces" field is omitted.
   (4) tr_file's "firstPiece", "lastPiece", and "offset" fields are omitted.

   Note that this is a fairly high-bandwidth request and that its results
   don't change.  You should try to cache its results instead of re-calling it.

   Example Request: 

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

   Example Response:

      {
         "tag": 39693
         "result": "success",
         "arguments": {
            "torrent-info": [ 
               { 
                  "id": 7, 
                  "name": "Ubuntu x86_64 DVD", 
                  "pieceCount": 1209233, 
                  "pieceSize": 4096, 
                  "totalSize": 9803930483, 
                  ... 
               }, 
               { 
                  "id": 10, 
                  "name": "Ubuntu i386 DVD", 
                  "pieceCount": 83943, 
                  "pieceSize": 12345, 
                  "totalSize": 2398480394, 
                  ... 
               } 
            ]
         }
      }

3.4.  Torrent Status Requests

   Method name: "torrent-status"

   Request arguments: 3.1's optional "ids" argument.

   Response arguments: "torrent-status", an array of objects based
   on libtransmission's tr_stat struct but differerent in the
   following ways:

   (1) the torrent's "id" field is added.
   (2) tr_info's "name" field is added.
   (3) tr_stat's "tracker" field is omitted, and is instead
       replaced with two strings: "announce-url" and scrape-url"

3.5.  Adding a Torrent

   Method name: "torrent-add"

   Request arguments:

   string             | 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.

3.6.  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.6.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.6.2.  Accessors

   Method name: "torrent-get"
   Request arguments: none
   Response arguments: A "torrents" list of objects containing all
                       of 3.6's arguments plus the torrent's "id" int.
                      

3.7  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.7.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.7.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" | int      max global download speed (in KiB/s)
   "speed-limit-up"           | int      max global upload speed (in KiB/s)
   "speed-limit-up-enabled"   | int      max global upload speed (in KiB/s)

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