source: branches/1.6x/doc/rpc-spec.txt

Last change on this file was 8259, checked in by charles, 8 years ago

(trunk) #1997: rpc spec cleanup

File size: 27.1 KB
Line 
11.  Introduction
2
3   This document describes a protocol for interacting with Transmission
4   sessions remotely.
5
61.1  Terminology
7
8   The JSON terminology in RFC 4627 is used.
9
10   In benc terms, a JSON "array" is equivalent to a benc list,
11   a JSON "object" is equivalent to a benc dictionary,
12   and a JSON object's "keys" are the dictionary's string keys.
13
142.  Message Format
15
16   Messages are formatted as objects.  There are two types:
17   requests (described in 2.1) and responses (described in 2.2).
18
19   All text MUST be UTF-8 encoded.
20
212.1.  Requests
22
23   Requests support three keys:
24
25   (1) A required "method" string telling the name of the method to invoke
26   (2) An optional "arguments" object of key/value pairs
27   (3) An optional "tag" number used by clients to track responses.
28       If provided by a request, the response MUST include the same tag.
29
302.2.  Responses
31
32   Reponses support three keys:
33
34   (1) A required "result" string whose value MUST be "success" on success,
35       or an error string on failure.
36   (2) An optional "arguments" object of key/value pairs
37   (3) An optional "tag" number as described in 2.1.
38
392.3.  Transport Mechanism
40
41   HTTP POSTing a JSON-encoded request is the preferred way of communicating
42   with a Transmission RPC server.  The current Transmission implementation
43   has the default URL as http://host:9091/transmission/rpc.  Clients
44   may use this as a default, but should allow the URL to be reconfigured,
45   since the port and path may be changed to allow mapping and/or multiple
46   daemons to run on a single server.
47
48   In addition to POSTing, there's also a simple notation for sending
49   requests in the query portion of a URL.  This is not as robust, but can
50   be useful for debugging and simple tasks.  The notation works as follows:
51
52   (1) Any key not "tag" or "method" is treated as an argument.
53   (2) The "arguments" key isn't needed, since data isn't nested.
54   (3) If the value in a key/value pair can be parsed as a number, then it is.
55       Otherwise if it can be parsed as an array of numbers, then it is.
56       Otherwise, it's parsed as a string.
57
58   Examples:
59   ?method=torrent-start&ids=1,2
60   ?method=session-set&speed-limit-down=50&speed-limit-down-enabled=1
61   
62
633.  Torrent Requests
64
653.1.  Torrent Action Requests
66
67   Method name          | libtransmission function
68   ---------------------+-------------------------------------------------
69   "torrent-start"      | tr_torrentStart
70   "torrent-stop"       | tr_torrentStop
71   "torrent-verify"     | tr_torrentVerify
72   "torrent-reannounce" | tr_torrentManualUpdate ("ask tracker for more peers")
73
74   Request arguments: "ids", which specifies which torrents to use.
75                      All torrents are used if the "ids" argument is omitted.
76                      "ids" should be one of the following:
77                      (1) an integer referring to a torrent id
78                      (2) a list of torrent id numbers, sha1 hash strings, or both
79                      (3) a string, "recently-active", for recently-active torrents
80
81   Response arguments: none
82
833.2.  Torrent Mutators
84
85   Method name: "torrent-set"
86
87   Request arguments:
88
89   string                            | value type & description
90   ----------------------------------+-------------------------------------------------
91   "bandwidthPriority"               | number     this torrent's bandwidth tr_priority_t
92   "downloadLimit"                   | number     maximum download speed (in K/s)
93   "downloadLimited"                 | boolean    true if "downloadLimit" is honored
94   "files-wanted"                    | array      indices of file(s) to download
95   "files-unwanted"                  | array      indices of file(s) to not download
96   "honorsSessionLimits"             | boolean    true if session upload limits are honored
97   "ids"                             | array      torrent list, as described in 3.1
98   "peer-limit"                      | number     maximum number of peers
99   "priority-high"                   | array      indices of high-priority file(s)
100   "priority-low"                    | array      indices of low-priority file(s)
101   "priority-normal"                 | array      indices of normal-priority file(s)
102   "seedRatioLimit"                  | double     session seeding ratio
103   "seedRatioMode"                   | number     which ratio to use.  See tr_ratiolimit
104   "uploadLimit"                     | number     maximum upload speed (in K/s)
105   "uploadLimited"                   | boolean    true if "uploadLimit" is honored
106
107   Just as an empty "ids" value is shorthand for "all ids", using an empty array
108   for "files-wanted", "files-unwanted", "priority-high", "priority-low", or
109   "priority-normal" is shorthand for saying "all files".
110
111   Response arguments: none
112
1133.3.  Torrent Accessors
114
115   Method name: "torrent-get".
116
117   Request arguments:
118
119   (1) An opional "ids" array as described in 3.1.
120   (2) A required "fields" array of keys. (see list below)
121
122   Response arguments:
123
124   (1) A "torrents" array of objects, each of which contains
125       the key/value pairs matching the request's "fields" argument.
126   (2) If the request's "ids" field was "recently-active",
127       a "removed" array of torrent-id numbers of recently-removed
128       torrents.
129
130   key                             | type                        | source
131   --------------------------------+-----------------------------+---------
132   activityDate                    | number                      | tr_stat
133   addedDate                       | number                      | tr_stat
134   announceResponse                | string                      | tr_stat
135   announceURL                     | string                      | tr_stat
136   bandwidthPriority               | number                      | tr_priority_t
137   comment                         | string                      | tr_info
138   corruptEver                     | number                      | tr_stat
139   creator                         | string                      | tr_info
140   dateCreated                     | number                      | tr_info
141   desiredAvailable                | number                      | tr_stat
142   doneDate                        | number                      | tr_stat
143   downloadDir                     | string                      | tr_torrent
144   downloadedEver                  | number                      | tr_stat
145   downloaders                     | number                      | tr_stat
146   downloadLimit                   | number                      | tr_torrent
147   downloadLimited                 | boolean                     | tr_torrent
148   error                           | number                      | tr_stat
149   errorString                     | number                      | tr_stat
150   eta                             | number                      | tr_stat
151   files                           | array (see below)           | n/a
152   fileStats                       | array (see below)           | n/a
153   hashString                      | string                      | tr_info
154   haveUnchecked                   | number                      | tr_stat
155   haveValid                       | number                      | tr_stat
156   honorsSessionLimits             | boolean                     | tr_torrent
157   id                              | number                      | tr_torrent
158   isPrivate                       | boolean                     | tr_torrent
159   lastAnnounceTime                | number                      | tr_stat
160   lastScrapeTime                  | number                      | tr_stat
161   leechers                        | number                      | tr_stat
162   leftUntilDone                   | number                      | tr_stat
163   manualAnnounceTime              | number                      | tr_stat
164   maxConnectedPeers               | number                      | tr_torrent
165   name                            | string                      | tr_info
166   nextAnnounceTime                | number                      | tr_stat
167   nextScrapeTime                  | number                      | tr_stat
168   peer-limit                      | number                      | tr_torrent
169   peers                           | array (see below)           | n/a
170   peersConnected                  | number                      | tr_stat
171   peersFrom                       | object (see below)          | n/a
172   peersGettingFromUs              | number                      | tr_stat
173   peersKnown                      | number                      | tr_stat
174   peersSendingToUs                | number                      | tr_stat
175   percentDone                     | double                      | tr_stat
176   pieces                          | string (see below)          | tr_torrent
177   pieceCount                      | tnumber                     | tr_info
178   pieceSize                       | tnumber                     | tr_info
179   priorities                      | array (see below)           | n/a
180   rateDownload (B/s)              | number                      | tr_stat
181   rateUpload (B/s)                | number                      | tr_stat
182   recheckProgress                 | double                      | tr_stat
183   scrapeResponse                  | string                      | tr_stat
184   scrapeURL                       | string                      | tr_stat
185   seeders                         | number                      | tr_stat
186   seedRatioLimit                  | double                      | tr_torrent
187   seedRatioMode                   | number                      | tr_ratiolimit
188   sizeWhenDone                    | number                      | tr_stat
189   startDate                       | number                      | tr_stat
190   status                          | number                      | tr_stat
191   swarmSpeed (K/s)                | number                      | tr_stat
192   timesCompleted                  | number                      | tr_stat
193   trackers                        | array (see below)           | n/a
194   totalSize                       | number                      | tr_info
195   torrentFile                     | string                      | tr_info
196   uploadedEver                    | number                      | tr_stat
197   uploadLimit                     | number                      | tr_torrent
198   uploadLimited                   | boolean                     | tr_torrent
199   uploadRatio                     | double                      | tr_stat
200   wanted                          | array (see below)           | n/a
201   webseeds                        | array (see below)           | n/a
202   webseedsSendingToUs             | number                      | tr_stat
203                                   |                             |
204                                   |                             |
205   -----------------------+--------+-----------------------------+
206   files                  | array of objects, each containing:   |
207                          +-------------------------+------------+
208                          | key                     | type       |
209                          | bytesCompleted          | number     | tr_torrent
210                          | length                  | number     | tr_info
211                          | name                    | string     | tr_info
212   -----------------------+--------------------------------------+
213   fileStats              | a file's non-constant properties.    |
214                          | array of tr_info.filecount objects,  |
215                          | each containing:                     |
216                          +-------------------------+------------+
217                          | bytesCompleted          | number     | tr_torrent
218                          | wanted                  | boolean    | tr_info
219                          | priority                | number     | tr_info
220   -----------------------+--------------------------------------+
221   peers                  | array of objects, each containing:   |
222                          +-------------------------+------------+
223                          | address                 | string     | tr_peer_stat
224                          | clientName              | string     | tr_peer_stat
225                          | clientIsChoked          | boolean    | tr_peer_stat
226                          | clientIsInterested      | boolean    | tr_peer_stat
227                          | isDownloadingFrom       | boolean    | tr_peer_stat
228                          | isEncrypted             | boolean    | tr_peer_stat
229                          | isIncoming              | boolean    | tr_peer_stat
230                          | isUploadingTo           | boolean    | tr_peer_stat
231                          | peerIsChoked            | boolean    | tr_peer_stat
232                          | peerIsInterested        | boolean    | tr_peer_stat
233                          | port                    | number     | tr_peer_stat
234                          | progress                | double     | tr_peer_stat
235                          | rateToClient (B/s)      | number     | tr_peer_stat
236                          | rateToPeer (B/s)        | number     | tr_peer_stat
237   -----------------------+--------------------------------------+
238   peersFrom              | an object containing:                |
239                          +-------------------------+------------+
240                          | fromCache               | number     | tr_stat
241                          | fromIncoming            | number     | tr_stat
242                          | fromPex                 | number     | tr_stat
243                          | fromTracker             | number     | tr_stat
244   -----------------------+--------------------------------------+
245   pieces                 | A bitfield holding pieceCount flags  | tr_torrent
246                          | which are set to 'true' if we have   |
247                          | the piece matching that position.    |
248                          | JSON doesn't allow raw binary data,  |
249                          | so this is a base64-encoded string.  |
250   -----------------------+--------------------------------------+
251   priorities             | an array of tr_info.filecount        | tr_info
252                          | numbers. each is the tr_priority_t   |
253                          | mode for the corresponding file.     |
254   -----------------------+--------------------------------------+
255   trackers               | array of objects, each containing:   |
256                          +-------------------------+------------+
257                          | announce                | string     | tr_info
258                          | scrape                  | string     | tr_info
259                          | tier                    | number     | tr_info
260   -----------------------+--------------------------------------+
261   wanted                 | an array of tr_info.fileCount        | tr_info
262                          | 'booleans' true if the corresponding |
263                          | file is to be downloaded.            |
264   -----------------------+--------------------------------------+
265   webseeds               | an array of strings:                 |
266                          +-------------------------+------------+
267                          | webseed                 | string     | tr_info
268                          +-------------------------+------------+
269
270   Example:
271
272   Say we want to get the name and total size of torrents #7 and #10.
273
274   Request:
275
276      {
277         "arguments": {
278             "fields": [ "id", "name", "totalSize" ],
279             "ids": [ 7, 10 ]
280         },
281         "method": "torrent-get",
282         "tag": 39693
283      }
284
285
286   Response:
287
288      {
289         "arguments": {
290            "torrents": [
291               {
292                   "id": 10,
293                   "name": "Fedora x86_64 DVD",
294                   "totalSize", 34983493932,
295               },
296               {
297                   "id": 7,
298                   "name": "Ubuntu x86_64 DVD",
299                   "totalSize", 9923890123,
300               }
301            ]
302         },
303         "result": "success",
304         "tag": 39693
305      }
306
3073.4.  Adding a Torrent
308
309   Method name: "torrent-add"
310
311   Request arguments:
312
313   key                | value type & description
314   -------------------+-------------------------------------------------
315   "download-dir"     | string      path to download the torrent to
316   "filename"         | string      filename or URL of the .torrent file
317   "metainfo"         | string      base64-encoded .torrent content
318   "paused"           | boolean     if true, don't start the torrent
319   "peer-limit"       | number      maximum number of peers
320   "files-wanted"     | array       indices of file(s) to download
321   "files-unwanted"   | array       indices of file(s) to not download
322   "priority-high"    | array       indices of high-priority file(s)
323   "priority-low"     | array       indices of low-priority file(s)
324   "priority-normal"  | array       indices of normal-priority file(s)
325
326   Either "filename" OR "metainfo" MUST be included.
327   All other arguments are optional.
328
329   Response arguments: on success, a "torrent-added" object in the
330                       form of one of 3.3's tr_info objects with the
331                       fields for id, name, and hashString.
332
3333.5.  Removing a Torrent
334
335   Method name: "torrent-remove"
336
337   Request arguments:
338
339   string                     | value type & description
340   ---------------------------+-------------------------------------------------
341   "ids"                      | array      torrent list, as described in 3.1
342   "delete-local-data"        | boolean    delete local data. (default: false)
343
344   Response arguments: none
345
346
3474.   Session Requests
348
3494.1.  Session Arguments
350
351   string                     | value type & description
352   ---------------------------+-------------------------------------------------
353   "alt-speed-down"           | number     max global download speed (in K/s)
354   "alt-speed-enabled"        | boolean    true means use the alt speeds
355   "alt-speed-time-begin"     | number     when to turn on alt speeds (units: minutes after midnight)
356   "alt-speed-time-enabled"   | boolean    true means the scheduled on/off times are used
357   "alt-speed-time-end"       | number     when to turn off alt speeds (units: same)
358   "alt-speed-time-day"       | number     what day(s) to turn on alt speeds (look at tr_sched_day)
359   "alt-speed-up"             | number     max global upload speed (in K/s)
360   "blocklist-enabled"        | boolean    true means enabled
361   "blocklist-size"           | number     number of rules in the blocklist
362   "encryption"               | string     "required", "preferred", "tolerated"
363   "download-dir"             | string     default path to download torrents
364   "peer-limit-global"        | number     maximum global number of peers
365   "peer-limit-per-torrent"   | number     maximum global number of peers
366   "pex-enabled"              | boolean    true means allow pex in public torrents
367   "peer-port"                | number     port number
368   "peer-port-random-on-start"| boolean    true means pick a random peer port on launch
369   "port-forwarding-enabled"  | boolean    true means enabled
370   "rpc-version"              | number     the current RPC API version
371   "rpc-version-minimum"      | number     the minimum RPC API version supported
372   "seedRatioLimit"           | double     the default seed ratio for torrents to use
373   "seedRatioLimited"         | boolean    true if seedRatioLimit is honored by default
374   "speed-limit-down"         | number     max global download speed (in K/s)
375   "speed-limit-down-enabled" | boolean    true means enabled
376   "speed-limit-up"           | number     max global upload speed (in K/s)
377   "speed-limit-up-enabled"   | boolean    true means enabled
378   "version"                  | string     long version string "$version ($revision)"
379
380   "rpc-version" indicates the RPC interface version supported by the RPC server.
381   It is incremented when a new version of Transmission changes the RPC interface.
382
383   "rpc-version-minimum" indicates the oldest API supported by the RPC server.
384   It is changes when a new version of Transmission changes the RPC interface
385   in a way that is not backwards compatible.  There are no plans for this
386   to be common behavior.
387
3884.1.1.  Mutators
389
390   Method name: "session-set"
391   Request arguments: one or more of 4.1's arguments, except: "blocklist-size",
392                      "rpc-version", "rpc-version-minimum", and "version"
393   Response arguments: none
394
3954.1.2.  Accessors
396
397   Method name: "session-get"
398   Request arguments: none
399   Response arguments: all of 4.1's arguments
400
4014.2.  Session Statistics
402
403   Method name: "session-stats"
404
405   Request arguments: none
406
407   Response arguments:
408
409   string                     | value type
410   ---------------------------+-------------------------------------------------
411   "activeTorrentCount"       | number
412   "downloadSpeed"            | number
413   "pausedTorrentCount"       | number
414   "torrentCount"             | number
415   "uploadSpeed"              | number
416   ---------------------------+-------------------------------+
417   "cumulative-stats"         | object, containing:           |
418                              +------------------+------------+
419                              | uploadedBytes    | number     | tr_session_stats
420                              | downloadedBytes  | number     | tr_session_stats
421                              | filesAdded       | number     | tr_session_stats
422                              | sessionCount     | number     | tr_session_stats
423                              | secondsActive    | number     | tr_session_stats
424   ---------------------------+-------------------------------+
425   "current-stats"            | object, containing:           |
426                              +------------------+------------+
427                              | uploadedBytes    | number     | tr_session_stats
428                              | downloadedBytes  | number     | tr_session_stats
429                              | filesAdded       | number     | tr_session_stats
430                              | sessionCount     | number     | tr_session_stats
431                              | secondsActive    | number     | tr_session_stats
432
4334.3.  Blocklist
434
435   Method name: "blocklist-update"
436   Request arguments: none
437   Response arguments: a number "blocklist-size"
438
4394.4.  Port Checking
440
441   This method tests to see if your incoming peer port is accessible
442   from the outside world.
443
444   Method name: "port-test"
445   Request arguments: none
446   Response arguments: a bool, "port-is-open"
447
4485.0.  Protocol Versions
449
450  The following changes have been made to the RPC interface:
451
452   RPC   | Release | Backwards |                |
453   Vers. | Version | Compat?   | Method         | Description
454   ------+---------+-----------+----------------+-------------------------------
455   1     | 1.30    | n/a       | n/a            | Initial version
456   ------+---------+-----------+----------------+-------------------------------
457   2     | 1.34    | yes       | torrent-get    | new arg "peers"
458   ------+---------+-----------+----------------+-------------------------------
459   3     | 1.41    | yes       | torrent-get    | added "port" to "peers"
460         |         | yes       | torrent-get    | new arg "downloaders"
461         |         | yes       | session-get    | new arg "version"
462         |         | yes       | torrent-remove | new method
463   ------+---------+-----------+----------------+-------------------------------
464   4     | 1.50    | yes       | session-get    | new arg "rpc-version"
465         |         | yes       | session-get    | new arg "rpc-version-minimum"
466         |         | yes       | session-stats  | added "cumulative-stats"
467         |         | yes       | session-stats  | added "current-stats"
468         |         | yes       | torrent-get    | new arg "downloadDir"
469   ------+---------+-----------+----------------+-------------------------------
470   5     | 1.60    | yes       |                | new method "torrent-reannounce"
471         |         | yes       |                | new method "blocklist-update"
472         |         | yes       |                | new method "port-test"
473         |         |           |                |
474         |         | yes       | session-get    | new arg "alt-speed-begin"
475         |         | yes       | session-get    | new arg "alt-speed-down"
476         |         | yes       | session-get    | new arg "alt-speed-enabled"
477         |         | yes       | session-get    | new arg "alt-speed-end"
478         |         | yes       | session-get    | new arg "alt-speed-time-enabled"
479         |         | yes       | session-get    | new arg "alt-speed-up"
480         |         | yes       | session-get    | new arg "blocklist-enabled"
481         |         | yes       | session-get    | new arg "blocklist-size"
482         |         | yes       | session-get    | new arg "peer-limit-per-torrent"
483         |         | yes       | session-get    | new arg "seedRatioLimit"
484         |         | yes       | session-get    | new arg "seedRatioLimited"
485         |         |        NO | session-get    | renamed "pex-allowed" to "pex-enabled"
486         |         |        NO | session-get    | renamed "port" to "peer-port"
487         |         |        NO | session-get    | renamed "peer-limit" to "peer-limit-global"
488         |         |           |                |
489         |         | yes       | torrent-add    | new arg "files-unwanted"
490         |         | yes       | torrent-add    | new arg "files-wanted"
491         |         | yes       | torrent-add    | new arg "priority-high"
492         |         | yes       | torrent-add    | new arg "priority-low"
493         |         | yes       | torrent-add    | new arg "priority-normal"
494         |         |           |                |
495         |         | yes       | torrent-set    | new arg "bandwidthPriority"
496         |         | yes       | torrent-set    | new arg "honorsSessionLimits"
497         |         | yes       | torrent-set    | new arg "seedRatioLimit"
498         |         | yes       | torrent-set    | new arg "seedRatioLimited"
499         |         |        NO | torrent-set    | renamed "speed-limit-down" to "downloadLimit"
500         |         |        NO | torrent-set    | renamed "speed-limit-down-enabled" to "downloadLimited"
501         |         |        NO | torrent-set    | renamed "speed-limit-up" to "uploadLimit"
502         |         |        NO | torrent-set    | renamed "speed-limit-up-enabled" to "uploadLimited"
503         |         |           |                |
504         |         | yes       | torrent-get    | new arg "bandwidthPriority"
505         |         | yes       | torrent-get    | new arg "fileStats"
506         |         | yes       | torrent-get    | new arg "honorsSessionLimits"
507         |         | yes       | torrent-get    | new arg "percentDone"
508         |         | yes       | torrent-get    | new arg "pieces"
509         |         | yes       | torrent-get    | new arg "seedRatioLimit"
510         |         | yes       | torrent-get    | new arg "seedRatioMode"
511         |         | yes       | torrent-get    | new arg "torrentFile"
512         |         | yes       | torrent-get    | new ids option "recently-active"
513         |         |        NO | torrent-get    | removed arg "downloadLimitMode"
514         |         |        NO | torrent-get    | removed arg "uploadLimitMode"
515   ------+---------+-----------+----------------+-------------------------------
516
517
Note: See TracBrowser for help on using the repository browser.