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. 3. Torrent Requests 3.1. Torrent Action Requests Method names: "torrent-start", "torrent-stop", "torrent-remove", "torrent-verify" 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 Info Requests Method 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: { "arguments": { "ids": [ 7, 10 ] } "method": "torrent-info", "tag": 39693 } Example Response: { "tag": 39693 "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.3. Torrent Status Requests Method name: "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 in 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.4. Adding a Torrent Method name: "torrent-add" Request arguments: string | value type & description -------------------+------------------------------------------------- "destination" | string path to download the torrent to "filename" | string location of the .torrent file "paused" | boolean if true, don't start the torrent "peer-limit" | int maximum number of peers The "filename" argument is required; all others are optional. Response arguments: on success, a "torrent-added" object in the form of one of 3.2's tr_info objects. 3.5. 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.5.1. Mutators Method name: "torrent-set" Request arguments: 3.1's "ids", plus one or more of 3.5's arguments Response arguments: none 3.5.2. Accessors Method name: "torrent-get" Request arguments: none Response arguments: A "torrents" list of objects containing all of 3.5's arguments plus the torrent's "id" int. 3.6 File Priorities Common arguments: string | value type & description -------------------+------------------------------------------------- "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.6.1. Mutators Method name: "torrent-set-priorities" 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-priorities" Request arguments: none Response arguments: A "torrents" list of objects containing all of 3.6'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" "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