-
Notifications
You must be signed in to change notification settings - Fork 7
/
rpc-spec.txt
1293 lines (1081 loc) · 69.2 KB
/
rpc-spec.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1. Introduction
This document describes a protocol for interacting with BiglyBT and
Transmission sessions remotely. Updated from
https://github.com/transmission/transmission/blob/master/extras/rpc-spec.txt
to include BiglyBT additions.
1.1 Terminology
The JSON terminology in RFC 4627 is used.
JSON is fairly common now, but for the benefit of
torrent developers familiar with benc:
a JSON array is equivalent to a benc list,
a JSON object is equivalent to a benc dictionary,
and a JSON object's keys are the dictionary's string keys.
1.2 Resources
The command-line utility "transmission-remote" uses this RPC API.
Several developers have reported using its --debug JSON output as
a reference when developing/debugging their own code.
2. Message Format
Messages are formatted as objects. There are two types:
requests (described in 2.1) and responses (described in 2.2).
All text MUST be UTF-8 encoded.
2.1. Requests
Requests support 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" number used by clients to track responses.
If provided by a request, the response MUST include the same tag.
2.2. Responses
Responses 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" number as described in 2.1.
2.3. Transport Mechanism
HTTP POSTing a JSON-encoded request is the preferred way of communicating
with a Transmission RPC server. The current Transmission implementation
has the default URL as http://host:9091/transmission/rpc. Clients
may use this as a default, but should allow the URL to be reconfigured,
since the port and path may be changed to allow mapping and/or multiple
daemons to run on a single server.
2.3.1. CSRF Protection
Most Transmission RPC servers require a X-Transmission-Session-Id
header to be sent with requests, to prevent CSRF attacks.
When your request has the wrong id -- such as when you send your first
request, or when the server expires the CSRF token -- the
Transmission RPC server will return an HTTP 409 error with the
right X-Transmission-Session-Id in its own headers.
So, the correct way to handle a 409 response is to update your
X-Transmission-Session-Id and to resend the previous request.
3. Torrent Requests
3.1. Torrent Action Requests
Method name | libtransmission function
---------------------+-------------------------------------------------
"torrent-start" | tr_torrentStart
"torrent-start-now" | tr_torrentStartNow
"torrent-stop" | tr_torrentStop
"torrent-verify" | tr_torrentVerify
"torrent-reannounce" | tr_torrentManualUpdate ("ask tracker for more peers")
Request arguments: "ids", which specifies which torrents to use.
All torrents are used if the "ids" argument is omitted.
"ids" should be one of the following:
(1) an integer referring to a torrent id
(2) a list of torrent id numbers, sha1 hash strings, or both
(3) a string, "recently-active", for recently-active torrents
Response arguments: none
3.2. Torrent Mutators
Method name: "torrent-set"
Request arguments:
string | value type & description
----------------------+-------------------------------------------------
"bandwidthPriority" | number this torrent's bandwidth tr_priority_t
"downloadLimit" | number maximum download speed (KBps)
"downloadLimited" | boolean true if "downloadLimit" is honored
"files-wanted" | array indices of file(s) to download
"files-unwanted" | array indices of file(s) to not download
"honorsSessionLimits" | boolean true if session upload limits are honored
"ids" | array torrent list, as described in 3.1
"labels" | array array of string labels
"location" | string new location of the torrent's content
"peer-limit" | number maximum number of peers
"priority-high" | array indices of high-priority file(s)
"priority-low" | array indices of low-priority file(s)
"priority-normal" | array indices of normal-priority file(s)
"queuePosition" | number position of this torrent in its queue [0...n)
"seedIdleLimit" | number torrent-level number of minutes of seeding inactivity
"seedIdleMode" | number which seeding inactivity to use. See tr_idlelimit
"seedRatioLimit" | double torrent-level seeding ratio
"seedRatioMode" | number which ratio to use. See tr_ratiolimit
>>> BiglyBT
"tagAdd" | array list of string (tag names) or number (tag uid) to add to torrent
"tagRemove" | array list of string (tag names) or number (tag uid) to remove from torrent
<<< BiglyBT
"trackerAdd" | array strings of announce URLs to add
"trackerRemove" | array ids of trackers to remove
"trackerReplace" | array pairs of <trackerId/new announce URLs>
"uploadLimit" | number maximum upload speed (KBps)
"uploadLimited" | boolean true if "uploadLimit" is honored
>>> VUZE
"name" | string new display name for the torrent
"files" | array of map
key | value type & description
---------------------+-------------------------------------------------
"index" | index (position) of file in torrent (mandatory)
"name" | new name for file
<<< VUZE
Just as an empty "ids" value is shorthand for "all ids", using an empty array
for "files-wanted", "files-unwanted", "priority-high", "priority-low", or
"priority-normal" is shorthand for saying "all files".
Response arguments: none
3.3. Torrent Accessors
Method name: "torrent-get".
Request arguments:
(1) An optional "ids" array as described in 3.1.
(2) A required "fields" array of keys. (see list below)
(3) An optional "format" string specifying how to format the
"torrents" response field. Allowed values are "objects" (default)
and "table". (see "Response arguments" below)
Response arguments:
(1) A "torrents" array.
If the "format" request was "objects" (default), "torrents" will
be an array of objects, each of which contains the key/value
pairs matching the request's "fields" arg. This was the only
format before Transmission 3 and has some obvious programmer
conveniences, such as parsing directly into Javascript objects.
If the format was "table", then "torrents" will be an array of
arrays. The first row holds the keys and each remaining row holds
a torrent's values for those keys. This format is more efficient
in terms of JSON generation and JSON parsing.
>>> BiglyBT
Essentially this saves sending the field keys over and over again, and
is a similar concept to BiglyBT's mapPerFile=false.
[
// Row 0: keys
[ field-key0, field-key1, ... ],
// Row 1: First Torrent
[ value for "field-key0", value for "field-key1", ... ],
// Row 2: 2nd Torrent
[ value for "field-key0", value for "field-key1", ... ],
// Row X: Xth Torrent
...
]
Note: for "files" and "fileStats", value will still be an array of map.
These maps will still have their keys ("bytesCompleted", "name", etc)
duplicated for every file, and every torrent.
BiglyBT has "mapPerFile" instead of "format", but it only
works for "files". When set to false, "files" will be an array of
arrays, and the keys will be in a field called "kileKeys" (not row 0)
BiglyBT also has a "file-fields" parameter that you can set to
limit the fields that "files" returns
<<< BiglyBT
(2) If the request's "ids" field was "recently-active",
a "removed" array of torrent-id numbers of recently-removed
torrents.
Note: For more information on what these fields mean, see the comments
in libtransmission/transmission.h. The "source" column here
corresponds to the data structure there.
key | type | source
----------------------------+-----------------------------+---------
activityDate | number | tr_stat
addedDate | number | tr_stat
bandwidthPriority | number | tr_priority_t
comment | string | tr_info
corruptEver | number | tr_stat
creator | string | tr_info
dateCreated | number | tr_info
desiredAvailable | number | tr_stat
doneDate | number | tr_stat
downloadDir | string | tr_torrent
downloadedEver | number | tr_stat
downloadLimit | number | tr_torrent
downloadLimited | boolean | tr_torrent
editDate | number | tr_stat
| The last time during this session that a rarely-changing field
| changed -- e.g. any tr_info field (trackers, filenames, name)
| or download directory. RPC clients can monitor this to know when
| to reload fields that rarely change.
error | number | tr_stat
errorString | string | tr_stat
eta | number | tr_stat
etaIdle | number | tr_stat
file-count | number | tr_info
files | array (see below) | n/a
>>> BiglyBT
file-fields | array of "files" fields to return in "files" map
| If missing, all files fields are returned
| (when "files" is in the "fields" list)
files-hc-<torrentid> | array of string
| A hashcode for each file (length must be # of files in torrent)
| File will only be returned in "files" if the file has changed.
| (when "files" is in the "fields" list)
file-indexes-<torrentid> | array of number
| "files" result will only contain files at
| the indexes specified
| If missing, all files will be returned
| (when "files" is in the "fields" list)
<<< BiglyBT
fileStats | array (see below) | n/a
hashString | string | tr_info
haveUnchecked | number | tr_stat
haveValid | number | tr_stat
honorsSessionLimits | boolean | tr_torrent
id | number | tr_torrent
isFinished | boolean | tr_stat
isPrivate | boolean | tr_torrent
isStalled | boolean | tr_stat
labels | array (see below) | tr_torrent
leftUntilDone | number | tr_stat
magnetLink | string | n/a
manualAnnounceTime | number | tr_stat
maxConnectedPeers | number | tr_torrent
metadataPercentComplete | double [0-1] | tr_stat
| How much of the metadata the torrent has.
| For torrents added from a .torrent this will always be 1.
| For magnet links, this number will from from 0 to 1 as the metadata is downloaded.
name | string | tr_info
peer-limit | number | tr_torrent
peers | array (see below) | n/a
>>> BiglyBT
peer-fields | array of "peers" fields to return in "peers" map
| if missing, all peers fields are returned
| (when "peers" is in the "fields" list)
<<< BiglyBT
peersConnected | number | tr_stat
| Number of peers that we're connected to
peersFrom | object (see below) | n/a
| How many peers we found out about from the tracker, or from pex,
| or from incoming connections, or from our resume file.
peersGettingFromUs | number | tr_stat
| Number of peers that we're sending data to
peersSendingToUs | number | tr_stat
| Number of peers that are sending data to us
percentDone | double | tr_stat
pieces | string (see below) | tr_torrent
pieceCount | number | tr_info
pieceSize | number | tr_info
priorities | array (see below) | n/a
primary-mime-type | string | tr_torrent
queuePosition | number | tr_stat
rateDownload (B/s) | number | tr_stat
rateUpload (B/s) | number | tr_stat
recheckProgress | double | tr_stat
secondsDownloading | number | tr_stat
secondsSeeding | number | tr_stat
seedIdleLimit | number | tr_torrent
seedIdleMode | number | tr_inactvelimit
seedRatioLimit | double | tr_torrent
seedRatioMode | number | tr_ratiolimit
sizeWhenDone | number | tr_stat
startDate | number | tr_stat
status | number | tr_stat
>>> BiglyBT
tag-uids | array of number. See "tags-get-list" method
<<< BiglyBT
trackers | array (see below) | n/a
trackerStats | array (see below) | n/a
totalSize | number | tr_info
torrentFile | string | tr_info
uploadedEver | number | tr_stat
uploadLimit | number | tr_torrent
uploadLimited | boolean | tr_torrent
uploadRatio | double | tr_stat
wanted | array (see below) | n/a
webseeds | array (see below) | n/a
webseedsSendingToUs | number | tr_stat
| |
| |
-------------------+--------+-----------------------------+
files | array of objects, each containing: |
+-------------------------+------------+
| bytesCompleted | number | tr_torrent
| length | number | tr_info
| name | string | tr_info
>>> BiglyBT
| index | number | file #
| | Useful if you requested a subset of files
| eta | number | eta in seconds to file completion
| contentURL | string | Streaming URL
| fullPath | string | Absolute path to file
| hc | string | hashcode for all fields requested.
| In future calls to torrent-get, adding a key "files-hc-<torrentid>"
| with a value of an array (length=# files in torrent). Each entry
| is a hc value. RPC will not return that file if nothing changed.
|--------------------------------------|
| You can also request fields from |
| "fileStats". |
| "name" field is relative to |
| "downloadDir", or absolute if file |
| has been moved outside of path. |
<<< BiglyBT
-------------------+--------------------------------------+
fileStats | a file's non-constant properties. |
| array of tr_info.filecount objects, |
| each containing: |
+-------------------------+------------+
| bytesCompleted | number | tr_torrent
| wanted | boolean | tr_info
| priority | number | tr_info
-------------------+--------------------------------------+
labels | an array of strings: |
+-------------------------+------------+
| label | string | tr_torrent
>>> BiglyBT
Note: There is no "label" key, it's jsut an array of strings
<<< BiglyBT
-------------------+--------------------------------------+
peers | array of objects, each containing: |
+-------------------------+------------+
| address | string | tr_peer_stat
| clientName | string | tr_peer_stat
| clientIsChoked | boolean | tr_peer_stat
| clientIsInterested | boolean | tr_peer_stat
| flagStr | string | tr_peer_stat
| isDownloadingFrom | boolean | tr_peer_stat
| isEncrypted | boolean | tr_peer_stat
| isIncoming | boolean | tr_peer_stat
| isUploadingTo | boolean | tr_peer_stat
| isUTP | boolean | tr_peer_stat
| peerIsChoked | boolean | tr_peer_stat
| peerIsInterested | boolean | tr_peer_stat
| port | number | tr_peer_stat
| progress | double | tr_peer_stat
| rateToClient (B/s) | number | tr_peer_stat
| rateToPeer (B/s) | number | tr_peer_stat
-------------------+--------------------------------------+
peersFrom | an object containing: |
+-------------------------+------------+
| fromCache | number | tr_stat
| fromDht | number | tr_stat
| fromIncoming | number | tr_stat
| fromLpd | number | tr_stat
| fromLtep | number | tr_stat
| fromPex | number | tr_stat
| fromTracker | number | tr_stat
-------------------+--------------------------------------+
pieces | A bitfield holding pieceCount flags | tr_torrent
| which are set to 'true' if we have |
| the piece matching that position. |
| JSON doesn't allow raw binary data, |
| so this is a base64-encoded string. |
-------------------+--------------------------------------+
priorities | an array of tr_info.filecount | tr_info
| numbers. each is the tr_priority_t |
| mode for the corresponding file. |
-------------------+--------------------------------------+
trackers | array of objects, each containing: |
+-------------------------+------------+
| announce | string | tr_tracker_info
| id | number | tr_tracker_info
| scrape | string | tr_tracker_info
| tier | number | tr_tracker_info
-------------------+--------------------------------------+
trackerStats | array of objects, each containing: |
+-------------------------+------------+
| announce | string | tr_tracker_stat
| announceState | number | tr_tracker_stat
| downloadCount | number | tr_tracker_stat
| hasAnnounced | boolean | tr_tracker_stat
| hasScraped | boolean | tr_tracker_stat
| host | string | tr_tracker_stat
| id | number | tr_tracker_stat
| isBackup | boolean | tr_tracker_stat
| lastAnnouncePeerCount | number | tr_tracker_stat
| lastAnnounceResult | string | tr_tracker_stat
| lastAnnounceStartTime | number | tr_tracker_stat
| lastAnnounceSucceeded | boolean | tr_tracker_stat
| lastAnnounceTime | number | tr_tracker_stat
| lastAnnounceTimedOut | boolean | tr_tracker_stat
| lastScrapeResult | string | tr_tracker_stat
| lastScrapeStartTime | number | tr_tracker_stat
| lastScrapeSucceeded | boolean | tr_tracker_stat
| lastScrapeTime | number | tr_tracker_stat
| lastScrapeTimedOut | boolean | tr_tracker_stat
| leecherCount | number | tr_tracker_stat
| nextAnnounceTime | number | tr_tracker_stat
| nextScrapeTime | number | tr_tracker_stat
| scrape | string | tr_tracker_stat
| scrapeState | number | tr_tracker_stat
| seederCount | number | tr_tracker_stat
| tier | number | tr_tracker_stat
-------------------+-------------------------+------------+
wanted | an array of tr_info.fileCount | tr_info
| 'booleans' true if the corresponding |
| file is to be downloaded. |
-------------------+--------------------------------------+
webseeds | an array of strings: |
+-------------------------+------------+
| webseed | string | tr_info
+-------------------------+------------+
Example:
Say we want to get the name and total size of torrents #7 and #10.
Request:
{
"arguments": {
"fields": [ "id", "name", "totalSize" ],
"ids": [ 7, 10 ]
},
"method": "torrent-get",
"tag": 39693
}
Response:
{
"arguments": {
"torrents": [
{
"id": 10,
"name": "Fedora x86_64 DVD",
"totalSize": 34983493932,
},
{
"id": 7,
"name": "Ubuntu x86_64 DVD",
"totalSize", 9923890123,
}
]
},
"result": "success",
"tag": 39693
}
3.4. Adding a Torrent
Method name: "torrent-add"
Request arguments:
key | value type & description
---------------------+-------------------------------------------------
"cookies" | string pointer to a string of one or more cookies.
"download-dir" | string path to download the torrent to
"filename" | string filename or URL of the .torrent file
"metainfo" | string base64-encoded .torrent content
"paused" | boolean if true, don't start the torrent
"peer-limit" | number maximum number of peers
"bandwidthPriority" | number torrent's bandwidth tr_priority_t
"files-wanted" | array indices of file(s) to download
"files-unwanted" | array indices of file(s) to not download
"priority-high" | array indices of high-priority file(s)
"priority-low" | array indices of low-priority file(s)
"priority-normal" | array indices of normal-priority file(s)
>>> BiglyBT
"vuze_tags" | array list of strings. Each string will be added
| as a tag. If the tag doesn't exist yet,
| it will be created.
<<< BiglyBT
Either "filename" OR "metainfo" MUST be included.
All other arguments are optional.
The format of the "cookies" should be NAME=CONTENTS, where NAME is the
cookie name and CONTENTS is what the cookie should contain.
Set multiple cookies like this: "name1=content1; name2=content2;" etc.
<http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTCOOKIE>
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.
On failure due to a duplicate torrent existing,
a "torrent-duplicate" object in the same form.
3.5. Removing a Torrent
Method name: "torrent-remove"
Request arguments:
string | value type & description
---------------------------+-------------------------------------------------
"ids" | array torrent list, as described in 3.1
"delete-local-data" | boolean delete local data. (default: false)
Response arguments: none
3.6. Moving a Torrent
Method name: "torrent-set-location"
Request arguments:
string | value type & description
---------------------------------+-------------------------------------------------
"ids" | array torrent list, as described in 3.1
"location" | string the new torrent location
"move" | boolean if true, move from previous location.
| otherwise, search "location" for files
| (default: false)
Response arguments: none
3.7. Renaming a Torrent's Path
Method name: "torrent-rename-path"
For more information on the use of this function, see the transmission.h
documentation of tr_torrentRenamePath(). In particular, note that if this
call succeeds you'll want to update the torrent's "files" and "name" field
with torrent-get.
Request arguments:
string | value type & description
---------------------------------+-------------------------------------------------
"ids" | array the torrent torrent list, as described in 3.1
| (must only be 1 torrent)
"path" | string the path to the file or folder that will be renamed
"name" | string the file or folder's new name
Response arguments: "path", "name", and "id", holding the torrent ID integer
4. Session Requests
4.1. Session Arguments
string | value type | description
---------------------------------+------------+-------------------------------------
"alt-speed-down" | number | max global download speed (KBps)
"alt-speed-enabled" | boolean | true means use the alt speeds
"alt-speed-time-begin" | number | when to turn on alt speeds (units: minutes after midnight)
"alt-speed-time-enabled" | boolean | true means the scheduled on/off times are used
"alt-speed-time-end" | number | when to turn off alt speeds (units: same)
"alt-speed-time-day" | number | what day(s) to turn on alt speeds (look at tr_sched_day)
"alt-speed-up" | number | max global upload speed (KBps)
"blocklist-url" | string | location of the blocklist to use for "blocklist-update"
"blocklist-enabled" | boolean | true means enabled
"blocklist-size" | number | number of rules in the blocklist
"cache-size-mb" | number | maximum size of the disk cache (MB)
"config-dir" | string | location of transmission's configuration directory
"download-dir" | string | default path to download torrents
"download-queue-size" | number | max number of torrents to download at once (see download-queue-enabled)
"download-queue-enabled" | boolean | if true, limit how many torrents can be downloaded at once
"dht-enabled" | boolean | true means allow dht in public torrents
"encryption" | string | "required", "preferred", "tolerated"
"idle-seeding-limit" | number | torrents we're seeding will be stopped if they're idle for this long
"idle-seeding-limit-enabled" | boolean | true if the seeding inactivity limit is honored by default
"incomplete-dir" | string | path for incomplete torrents, when enabled
"incomplete-dir-enabled" | boolean | true means keep torrents in incomplete-dir until done
"lpd-enabled" | boolean | true means allow Local Peer Discovery in public torrents
"peer-limit-global" | number | maximum global number of peers
"peer-limit-per-torrent" | number | maximum global number of peers
"pex-enabled" | boolean | true means allow pex in public torrents
"peer-port" | number | port number
"peer-port-random-on-start" | boolean | true means pick a random peer port on launch
"port-forwarding-enabled" | boolean | true means enabled
"queue-stalled-enabled" | boolean | whether or not to consider idle torrents as stalled
"queue-stalled-minutes" | number | torrents that are idle for N minuets aren't counted toward seed-queue-size or download-queue-size
"rename-partial-files" | boolean | true means append ".part" to incomplete files
"rpc-version" | number | the current RPC API version
"rpc-version-minimum" | number | the minimum RPC API version supported
"script-torrent-done-filename" | string | filename of the script to run
"script-torrent-done-enabled" | boolean | whether or not to call the "done" script
"seedRatioLimit" | double | the default seed ratio for torrents to use
"seedRatioLimited" | boolean | true if seedRatioLimit is honored by default
"seed-queue-size" | number | max number of torrents to uploaded at once (see seed-queue-enabled)
"seed-queue-enabled" | boolean | if true, limit how many torrents can be uploaded at once
"speed-limit-down" | number | max global download speed (KBps)
"speed-limit-down-enabled" | boolean | true means enabled
"speed-limit-up" | number | max global upload speed (KBps)
"speed-limit-up-enabled" | boolean | true means enabled
"start-added-torrents" | boolean | true means added torrents will be started right away
"trash-original-torrent-files" | boolean | true means the .torrent file of added torrents will be deleted
"units" | object | see below
"utp-enabled" | boolean | true means allow utp
"version" | string | long version string "$version ($revision)"
---------------------------------+------------+-----------------------------+
units | object containing: |
+--------------+--------+------------------+
| speed-units | array | 4 strings: KB/s, MB/s, GB/s, TB/s
| speed-bytes | number | number of bytes in a KB (1000 for kB; 1024 for KiB)
| size-units | array | 4 strings: KB/s, MB/s, GB/s, TB/s
| size-bytes | number | number of bytes in a KB (1000 for kB; 1024 for KiB)
| memory-units | array | 4 strings: KB/s, MB/s, GB/s, TB/s
| memory-bytes | number | number of bytes in a KB (1000 for kB; 1024 for KiB)
+--------------+--------+------------------+
>>> BiglyBT
"rpc-supports" | array of string | various features remote client supports
| | "method:X" supports rpc method X
| | "method:X" supports rpc method X
"biglybt-version"
"rpc-i2p-address"
"rpc-tor-address"
"az-content-port"
"az-rpc-version"
<<< BiglyBT
"rpc-version" indicates the RPC interface version supported by the RPC server.
It is incremented when a new version of Transmission changes the RPC interface.
"rpc-version-minimum" indicates the oldest API supported by the RPC server.
It is changes when a new version of Transmission changes the RPC interface
in a way that is not backwards compatible. There are no plans for this
to be common behavior.
4.1.1. Mutators
Method name: "session-set"
Request arguments: one or more of 4.1's arguments, except: "blocklist-size",
"config-dir", "rpc-version", "rpc-version-minimum",
"version", and "session-id"
Response arguments: none
4.1.2. Accessors
Method name: "session-get"
Request arguments: an optional "fields" array of keys (see 4.1)
Response arguments: key/value pairs matching the request's "fields"
argument if present, or all supported fields (see 4.1) otherwise.
4.2. Session Statistics
Method name: "session-stats"
Request arguments: none
Response arguments:
string | value type
---------------------------+-------------------------------------------------
"activeTorrentCount" | number
"downloadSpeed" | number
"pausedTorrentCount" | number
"torrentCount" | number
"uploadSpeed" | number
---------------------------+-------------------------------+
"cumulative-stats" | object, containing: |
+------------------+------------+
| uploadedBytes | number | tr_session_stats
| downloadedBytes | number | tr_session_stats
| filesAdded | number | tr_session_stats
| sessionCount | number | tr_session_stats
| secondsActive | number | tr_session_stats
---------------------------+-------------------------------+
"current-stats" | object, containing: |
+------------------+------------+
| uploadedBytes | number | tr_session_stats
| downloadedBytes | number | tr_session_stats
| filesAdded | number | tr_session_stats
| sessionCount | number | tr_session_stats
| secondsActive | number | tr_session_stats
4.3. Blocklist
Method name: "blocklist-update"
Request arguments: none
Response arguments: a number "blocklist-size"
4.4. Port Checking
This method tests to see if your incoming peer port is accessible
from the outside world.
Method name: "port-test"
Request arguments: none
Response arguments: a bool, "port-is-open"
4.5. Session shutdown
This method tells the transmission session to shut down.
Method name: "session-close"
Request arguments: none
Response arguments: none
4.6. Queue Movement Requests
Method name | libtransmission function
---------------------+-------------------------------------------------
"queue-move-top" | tr_torrentQueueMoveTop()
"queue-move-up" | tr_torrentQueueMoveUp()
"queue-move-down" | tr_torrentQueueMoveDown()
"queue-move-bottom" | tr_torrentQueueMoveBottom()
Request arguments:
string | value type & description
------------+----------------------------------------------------------
"ids" | array torrent list, as described in 3.1.
Response arguments: none
4.7. Free Space
This method tests how much free space is available in a
client-specified folder.
Method name: "free-space"
Request arguments:
string | value type & description
------------+----------------------------------------------------------
"path" | string the directory to query
Response arguments:
string | value type & description
------------+----------------------------------------------------------
"path" | string same as the Request argument
"size-bytes"| number the size, in bytes, of the free space in that directory
5.0. Protocol Versions
The following changes have been made to the RPC interface:
RPC | Release | Backwards | |
Vers. | Version | Compat? | Method | Description
------+---------+-----------+----------------------+-------------------------------
1 | 1.30 | n/a | n/a | Initial version
------+---------+-----------+----------------------+-------------------------------
2 | 1.34 | yes | torrent-get | new arg "peers"
------+---------+-----------+----------------------+-------------------------------
3 | 1.41 | yes | torrent-get | added "port" to "peers"
| | yes | torrent-get | new arg "downloaders"
| | yes | session-get | new arg "version"
| | yes | torrent-remove | new method
------+---------+-----------+----------------------+-------------------------------
4 | 1.50 | yes | session-get | new arg "rpc-version"
| | yes | session-get | new arg "rpc-version-minimum"
| | yes | session-stats | added "cumulative-stats"
| | yes | session-stats | added "current-stats"
| | yes | torrent-get | new arg "downloadDir"
------+---------+-----------+----------------------+-------------------------------
5 | 1.60 | yes | | new method "torrent-reannounce"
| | yes | | new method "blocklist-update"
| | yes | | new method "port-test"
| | | |
| | yes | session-get | new arg "alt-speed-begin"
| | yes | session-get | new arg "alt-speed-down"
| | yes | session-get | new arg "alt-speed-enabled"
| | yes | session-get | new arg "alt-speed-end"
| | yes | session-get | new arg "alt-speed-time-enabled"
| | yes | session-get | new arg "alt-speed-up"
| | yes | session-get | new arg "blocklist-enabled"
| | yes | session-get | new arg "blocklist-size"
| | yes | session-get | new arg "peer-limit-per-torrent"
| | yes | session-get | new arg "seedRatioLimit"
| | yes | session-get | new arg "seedRatioLimited"
| | NO | session-get | renamed "pex-allowed" to "pex-enabled"
| | NO | session-get | renamed "port" to "peer-port"
| | NO | session-get | renamed "peer-limit" to "peer-limit-global"
| | | |
| | yes | torrent-add | new arg "files-unwanted"
| | yes | torrent-add | new arg "files-wanted"
| | yes | torrent-add | new arg "priority-high"
| | yes | torrent-add | new arg "priority-low"
| | yes | torrent-add | new arg "priority-normal"
| | | |
| | yes | torrent-set | new arg "bandwidthPriority"
| | yes | torrent-set | new arg "honorsSessionLimits"
| | yes | torrent-set | new arg "seedRatioLimit"
| | yes | torrent-set | new arg "seedRatioLimited"
| | NO | torrent-set | renamed "speed-limit-down" to "downloadLimit"
| | NO | torrent-set | renamed "speed-limit-down-enabled" to "downloadLimited"
| | NO | torrent-set | renamed "speed-limit-up" to "uploadLimit"
| | NO | torrent-set | renamed "speed-limit-up-enabled" to "uploadLimited"
| | | |
| | yes | torrent-get | new arg "bandwidthPriority"
| | yes | torrent-get | new arg "fileStats"
| | yes | torrent-get | new arg "honorsSessionLimits"
| | yes | torrent-get | new arg "percentDone"
| | yes | torrent-get | new arg "pieces"
| | yes | torrent-get | new arg "seedRatioLimit"
| | yes | torrent-get | new arg "seedRatioMode"
| | yes | torrent-get | new arg "torrentFile"
| | yes | torrent-get | new ids option "recently-active"
| | NO | torrent-get | removed arg "downloadLimitMode"
| | NO | torrent-get | removed arg "uploadLimitMode"
------+---------+-----------+----------------------+-------------------------------
6 | 1.70 | yes | | new "method torrent-set-location"
------+---------+-----------+----------------------+-------------------------------
7 | 1.80 | NO | torrent-get | removed arg "announceResponse"
| | NO | torrent-get | removed arg "announceURL"
| | NO | torrent-get | removed arg "downloaders"
| | NO | torrent-get | removed arg "lastAnnounceTime"
| | NO | torrent-get | removed arg "lastScrapeTime"
| | NO | torrent-get | removed arg "leechers"
| | NO | torrent-get | removed arg "nextAnnounceTime"
| | NO | torrent-get | removed arg "nextScrapeTime"
| | NO | torrent-get | removed arg "scrapeResponse"
| | NO | torrent-get | removed arg "scrapeURL"
| | NO | torrent-get | removed arg "seeders"
| | NO | torrent-get | removed arg "timesCompleted"
| | NO | torrent-get | removed arg "swarmSpeed"
| | yes | torrent-get | new arg "magnetLink"
| | yes | torrent-get | new arg "metadataPercentComplete"
| | yes | torrent-get | new arg "trackerStats"
| | yes | session-set | new arg "incomplete-dir"
| | yes | session-set | new arg "incomplete-dir-enabled"
------+---------+-----------+----------------------+-------------------------------
8 | 1.90 | yes | session-set | new arg "rename-partial-files"
| | yes | session-get | new arg "rename-partial-files"
| | yes | session-get | new arg "config-dir"
| | yes | torrent-add | new arg "bandwidthPriority"
| | yes | torrent-get | new trackerStats arg "lastAnnounceTimedOut"
------+---------+-----------+----------------------+-------------------------------
8 | 1.92 | yes | torrent-get | new trackerStats arg "lastScrapeTimedOut"
------+---------+-----------+----------------------+-------------------------------
9 | 2.00 | yes | session-set | new arg "start-added-torrents"
| | yes | session-set | new arg "trash-original-torrent-files"
| | yes | session-get | new arg "start-added-torrents"
| | yes | session-get | new arg "trash-original-torrent-files"
| | yes | torrent-get | new arg "isFinished"
------+---------+-----------+----------------------+-------------------------------
10 | 2.10 | yes | session-get | new arg "cache-size-mb"
| | yes | torrent-set | new arg "trackerAdd"
| | yes | torrent-set | new arg "trackerRemove"
| | yes | torrent-set | new arg "trackerReplace"
| | yes | session-set | new arg "idle-seeding-limit"
| | yes | session-set | new arg "idle-seeding-limit-enabled"
| | yes | session-get | new arg "units"
| | yes | torrent-set | new arg "seedIdleLimit"
| | yes | torrent-set | new arg "seedIdleMode"
------+---------+-----------+----------------------+-------------------------------
11 | 2.12 | yes | session-get | new arg "blocklist-url"
| | yes | session-set | new arg "blocklist-url"
------+---------+-----------+----------------------+-------------------------------
12 | 2.20 | yes | session-get | new arg "download-dir-free-space"
| | yes | session-close | new method
------+---------+-----------+----------------------+-------------------------------
13 | 2.30 | yes | session-get | new arg "isUTP" to the "peers" list
| | yes | torrent-add | new arg "cookies"
| | NO | torrent-get | removed arg "peersKnown"
------+---------+-----------+----------------------+-------------------------------
14 | 2.40 | NO | torrent-get | values of "status" field changed
| | yes | torrent-get | new arg "queuePosition"
| | yes | torrent-get | new arg "isStalled"
| | yes | torrent-get | new arg "fromLpd" in peersFrom
| | yes | torrent-set | new arg "queuePosition"
| | yes | session-set | new arg "download-queue-size"
| | yes | session-set | new arg "download-queue-enabled"
| | yes | session-set | new arg "seed-queue-size"
| | yes | session-set | new arg "seed-queue-enabled"
| | yes | session-set | new arg "queue-stalled-enabled"
| | yes | session-set | new arg "queue-stalled-minutes"
| | yes | | new method "queue-move-top"
| | yes | | new method "queue-move-up"
| | yes | | new method "queue-move-down"
| | yes | | new method "queue-move-bottom"
| | yes | | new method "torrent-start-now"
------+---------+-----------+----------------------+-------------------------------
15 | 2.80 | yes | torrent-get | new arg "etaIdle"
| | yes | torrent-rename-path | new method
| | yes | free-space | new method
| | yes | torrent-add | new return arg "torrent-duplicate"
------+---------+-----------+----------------------+-------------------------------
16 | 3.00 | yes | session-get | new request arg "fields"
| | yes | session-get | new arg "session-id"
| | yes | torrent-get | new arg "labels"
| | yes | torrent-set | new arg "labels"
| | yes | torrent-get | new arg "editDate"
| | yes | torrent-get | new request arg "format"
------+---------+-----------+----------------------+-------------------------------
17 | 3.01 | yes | torrent-get | new arg "file-count"
| | yes | torrent-get | new arg "primary-mime-type"
5.1. Upcoming Breakage
These features will be removed three months after 2.80's release:
1. session-get's 'download-dir-free-space' argument will be removed.
Its functionality has been superceded by the 'free-space' method.
2. HTTP POSTs to http://server:port/transmission/upload will fail.
This was an undocumented hack to allow web clients to add files without
client-side access to the file. This functionality is superceded by
using HTML5's FileReader object + the documented 'torrent-add' method.
VZ.1 Start Search
Method name: "vuze-search-start"
az-rpc-version: 1
Request arguments:
key | value type & description
---------------------+-------------------------------------------------
"expression" | string search term
Response arguments:
key | value type & description
---------------------+-------------------------------------------------
"sid" | string Search ID to be used for result lookup
"engines" | array of map List of search engines available
key | value type & description
---------------------+-------------------------------------------------
"name" | string Name of search engine
"id" | string UID of search engine
"favicon" | string URL to icon
"dl_link_css" | string ?????
"selected" | string { "no", "auto", "manual" }
"source" | string { "unknown","vuze","local","rss","unused" }
"type" | depends { "unknown","regexp","json", "plugin", number }
VZ.2 Get Search Results
Method name: "vuze-search-get-results"
az-rpc-version: 1
Request arguments:
key | value type & description
---------------------+-------------------------------------------------
"sid" | string Search ID from vuze-search-start
Response arguments:
NOTE: numeric values are returned in strings
key | value type & description
---------------------+-------------------------------------------------
"sid" | string Search ID to be used for result lookup
"complete" | boolean Whether all engines have completed the search
| Once true, you will not be able to request for this sid again
"engines" | map List of search engines available
key | value type & description
---------------------+-------------------------------------------------
"id" | string UID of search engine
"error" | string If present, engine's error message
"complete" | boolean Whether the search has completed for this engine
"result" | array of map Search results
key | value type & description
---------------------+-------------------------------------------------
"d" | string Publish Date in "<time> <units> ago" or "unknown"
"ts" | string Numeric Publish Date or "0" if unkown
"c" | string Category
"n" | string Name
"s" | string Numeric # of seeds; "-1" if unknown
"p" | string Numeric # of peers; "-1" if unknown
"co" | string Comments
"l" | string Download size, friendly format (ex "50 kB"), or "-1" if unknown
"lb" | string Numeric download size in bytes, or "0" if unkown
"r" | string Numeric search ranking value
"ct" | string Content Type
"ac" | string If present, numeric (float) accuracy, "0" to "1"
"cdp" | string If present, URL to details page
"dl" | string If present, the download url
"dbl" | string If present, the download button url