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

2.  Message Format

   The entire protocol is 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 in benc.
   floating-point numbers are represented as strings.
   booleans are represented as integers where 0 is false and 1 is true.

   There are only two message types: request and response.  Both
   are JSON objects with two members:  "headers" (described in 2.1)
   and "body" (described in 2.2-2.3).

2.1.  Headers

   Message headers support two members:
   (1) A required "type" string whose value must be "request" or "response".
   (2) An optional "tag" integer supplied by requests for their own use.
       Responses MUST include the request tag's verbatim.

2.2.  Request Body

   Request bodies support two members:
   (1) A required "name" string telling the name of the request.
   (2) An optional "arguments" object of name/value pairs.

2.3.  Response Body

   All response bodies support two members:
   (1) A required "result" string whose value must be "success" on success,
       and may be "no-permission", "bad-format", or "error" on failure.
   (2) An optional "arguments" object of name/value pairs.
       The contents of these arguments depend on the request's name.

3.  Torrent Requests

3.1.  Common Arguments

   Most torrent requests support an "ids" argument, which is a list
   containing unique torrent ids, or torrent sha1 hash strings, or both.
   These are the torrents that the request will be applied to.
   If "ids" is omitted, the request is applied to all torrents.

3.2.  Torrent Action Requests

   Request names: "torrent-start", "torrent-stop",
                  "torrent-remove", "torrent-verify"
   Request arguments: 3.1's optional "ids" argument.
   Response arguments: none.

3.3.  Torrent Info Requests

   Request name: "torrent-info".
   Request arguments: 3.1's optional "ids" argument.

   Response arguments: "info", an array of objects based on libtransmission's
   tr_info struct but differ in the following ways:

   (1) tr_info's "hash" field is omitted.
   (2) tr_info's "pieces" field is omitted.
   (3) tr_file's "firstPiece", "lastPiece", and "offset" fields are omitted.

   Example Request: 

      {
         "headers": {
            "type": "request",
            "tag": 666
         },
         "body": {
            "name": "torrent-info",
            "arguments": {
               "ids": [ 7, 10 ]
            }
         }
      }

   Example Response:

      {
         "headers": {
            "type": "response",
            "tag": 666
         }
         "body": {
            "result": "success",
            "arguments": {
               "info": [
                  {
                     "id": 7,
                     "totalSize": 9803930483,
                     "pieceCount": 1209233,
                     "pieceSize": 4096,
                     "name": "Ubuntu x86_64 DVD",
                     ...
                  }
                  {
                     "id": 10,
                     "totalSize": 2398480394,
                     "pieceCount": 83943,
                     "pieceSize": 12345,
                     "name": "Ubuntu i386 DVD",
                     ...
                  }
               ]
            }
         }
      }

3.4.  Torrent Status Requests

   Request name is "torrent-status".
   Request arguments: 3.1's optional "ids" argument.

   Response arguments: "status", an array of objects based on
   libtransmission's tr_stat struct but which differ the following ways:

   (1) tr_stat's "tracker" field is omitted
   (2) a new string, "announce-url", is added
   (3) a new string, "scrape-url", is added

3.5.  Adding a Torrent

   Request name: "torrent-add"
   Request arguments:

   string             | value type & description
   -------------------+-------------------------------------------------
   "autostart"        | boolean   true means to auto-start torrents
   "directory"        | string    path to download the torrent to
   "filename"         | string    location of the .torrent file
   "max-peers"        | int       maximum number of peers
   "speed-limit-down" | int       maximum download speed (in KiB/s)
   "speed-limit-up"   | int       maximum upload speed (in KiB/s)

   The "filename" argument is required; all others are optional.

   Response arguments: 3.1's "error" if the request failed.

3.6.  Other torrent settings

   Common arguments:

   string             | value type & description
   -------------------+-------------------------------------------------
   "id"               | int or string  torrent id or hash string
   "max-peers"        | int            maximum number of peers
   "speed-limit-down" | int            maximum download speed (in KiB/s)
   "speed-limit-up"   | int            maximum upload speed (in KiB/s)

3.6.1.  Mutators

   Request name: "torrent-set"
   Request arguments: "id" from 3.6, plus one or more of 3.6's other arguments
   Response arguments: none

3.6.2.  Accessors

   Request name: "torrent-get"
   Request arguments: none
   Response arguments: all of 3.6's arguments

3.7  File Priorities

   Common arguments:

   string             | value type & description
   -------------------+-------------------------------------------------
   "id"               | int or string  torrent id or hash string
   "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
   "download"         | array          indices of one or more file to download
   "no-download"      | array          indices of one or more file to not download

3.7.1.  Mutators

    Request name: "torrent-set-file"
    Request arguments: "id" from 3.7, plus one or more of 3.7's other arguments
    Response arguments: none

3.7.2.  Accessors

    Request name: "torrent-get-file"
    Request arguments: none
    Response arguments: all of 3.7's arguments
   
4.   Session Status Requests

4.1.  Session Arguments

   string             | value type & description
   -------------------+-------------------------------------------------
   "autostart"        | boolean   true means to auto-start torrents
   "directory"        | string    path to download torrents to
   "encryption"       | string    "required", "preferred", or "plaintext"
   "max-peers"        | int       maximum global number of peers
   "port"             | int       port number
   "port-forwarding"  | boolean   true means enabled.
   "pex-allowed"      | boolean   true means allow pex for public torrents
   "speed-limit-down" | int       maximum global download speed (in KiB/s)
   "speed-limit-up"   | int       maximum global upload speed (in KiB/s)

4.2.  Mutators

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

4.2.  Accessors

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