2008-05-10 14:29:59 +00:00
|
|
|
1. Introduction
|
|
|
|
|
|
|
|
|
|
This document describes a protocol for interacting with Transmission
|
|
|
|
|
sessions remotely.
|
|
|
|
|
|
2008-05-10 16:11:00 +00:00
|
|
|
1.1 Terminology
|
|
|
|
|
|
2008-10-16 17:56:17 +00:00
|
|
|
The JSON terminology in RFC 4627 is used.
|
|
|
|
|
|
|
|
|
|
In benc terms, 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.
|
2008-05-10 14:29:59 +00:00
|
|
|
|
|
|
|
|
2. Message Format
|
|
|
|
|
|
2008-06-17 04:47:20 +00:00
|
|
|
Messages are formatted as objects. There are two types:
|
2008-05-12 23:51:17 +00:00
|
|
|
requests (described in 2.1) and responses (described in 2.2).
|
2008-05-10 14:29:59 +00:00
|
|
|
|
2008-08-20 01:55:28 +00:00
|
|
|
All text MUST be UTF-8 encoded.
|
|
|
|
|
|
2008-05-12 23:51:17 +00:00
|
|
|
2.1. Requests
|
2008-05-10 14:29:59 +00:00
|
|
|
|
2008-06-18 22:01:15 +00:00
|
|
|
Requests support three keys:
|
2008-05-10 14:29:59 +00:00
|
|
|
|
2008-05-12 23:51:17 +00:00
|
|
|
(1) A required "method" string telling the name of the method to invoke
|
2008-05-22 16:59:51 +00:00
|
|
|
(2) An optional "arguments" object of key/value pairs
|
2008-06-17 16:25:13 +00:00
|
|
|
(3) An optional "tag" number used by clients to track responses.
|
2008-05-12 23:51:17 +00:00
|
|
|
If provided by a request, the response MUST include the same tag.
|
2008-05-10 14:29:59 +00:00
|
|
|
|
2008-05-12 23:51:17 +00:00
|
|
|
2.2. Responses
|
2008-05-10 14:29:59 +00:00
|
|
|
|
2008-05-12 23:51:17 +00:00
|
|
|
Reponses support three keys:
|
2008-05-10 14:29:59 +00:00
|
|
|
|
2008-08-13 16:57:12 +00:00
|
|
|
(1) A required "result" string whose value MUST be "success" on success,
|
2008-05-12 23:51:17 +00:00
|
|
|
or an error string on failure.
|
2008-05-22 16:59:51 +00:00
|
|
|
(2) An optional "arguments" object of key/value pairs
|
2008-06-17 16:25:13 +00:00
|
|
|
(3) An optional "tag" number as described in 2.1.
|
2008-05-10 14:29:59 +00:00
|
|
|
|
2008-05-22 19:24:11 +00:00
|
|
|
2.3. Transport Mechanism
|
2008-05-15 05:11:50 +00:00
|
|
|
|
2008-06-17 16:25:13 +00:00
|
|
|
HTTP POSTing a JSON-encoded request is the preferred way of communicating
|
2009-02-10 18:19:09 +00:00
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
In addition to POSTing, there's also a simple notation for sending
|
|
|
|
|
requests in the query portion of a URL. This is not as robust, but can
|
|
|
|
|
be useful for debugging and simple tasks. The notation works as follows:
|
2008-05-15 05:11:50 +00:00
|
|
|
|
2008-06-17 04:47:20 +00:00
|
|
|
(1) Any key not "tag" or "method" is treated as an argument.
|
2008-05-15 05:11:50 +00:00
|
|
|
(2) The "arguments" key isn't needed, since data isn't nested.
|
2008-06-17 04:47:20 +00:00
|
|
|
(3) If the value in a key/value pair can be parsed as a number, then it is.
|
|
|
|
|
Otherwise if it can be parsed as an array of numbers, then it is.
|
|
|
|
|
Otherwise, it's parsed as a string.
|
2008-05-15 05:11:50 +00:00
|
|
|
|
|
|
|
|
Examples:
|
|
|
|
|
?method=torrent-start&ids=1,2
|
|
|
|
|
?method=session-set&speed-limit-down=50&speed-limit-down-enabled=1
|
2009-02-10 18:19:09 +00:00
|
|
|
|
2008-05-15 05:11:50 +00:00
|
|
|
|
2008-05-10 14:29:59 +00:00
|
|
|
3. Torrent Requests
|
|
|
|
|
|
2008-05-12 00:41:55 +00:00
|
|
|
3.1. Torrent Action Requests
|
2008-05-10 14:29:59 +00:00
|
|
|
|
2009-03-26 18:06:54 +00:00
|
|
|
Method name | libtransmission function
|
|
|
|
|
---------------------+-------------------------------------------------
|
|
|
|
|
"torrent-start" | tr_torrentStart
|
|
|
|
|
"torrent-stop" | tr_torrentStop
|
|
|
|
|
"torrent-verify" | tr_torrentVerify
|
|
|
|
|
"torrent-reannounce" | tr_torrentManualUpdate ("ask tracker for more peers")
|
2008-05-12 23:51:17 +00:00
|
|
|
|
2009-03-23 00:16:37 +00:00
|
|
|
Request arguments: "ids", which specifies which torrents to use.
|
2009-09-25 21:05:59 +00:00
|
|
|
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
|
2008-05-12 23:51:17 +00:00
|
|
|
|
2008-05-13 17:31:09 +00:00
|
|
|
Response arguments: none
|
2008-05-10 14:29:59 +00:00
|
|
|
|
2008-08-13 17:02:51 +00:00
|
|
|
3.2. Torrent Mutators
|
2008-05-10 14:29:59 +00:00
|
|
|
|
2008-06-17 16:25:13 +00:00
|
|
|
Method name: "torrent-set"
|
|
|
|
|
|
|
|
|
|
Request arguments:
|
2008-05-12 23:51:17 +00:00
|
|
|
|
2009-09-25 21:05:59 +00:00
|
|
|
string | value type & description
|
|
|
|
|
----------------------+-------------------------------------------------
|
|
|
|
|
"bandwidthPriority" | number this torrent's bandwidth tr_priority_t
|
2010-07-04 06:07:21 +00:00
|
|
|
"downloadLimit" | number maximum download speed (KBps)
|
2009-09-25 21:05:59 +00:00
|
|
|
"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
|
|
|
|
|
"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)
|
2010-07-24 02:57:39 +00:00
|
|
|
"seedIdleLimit" | number torrent-level number of minutes of seeding inactivity
|
|
|
|
|
"seedIdleMode" | number which seeding inactivity to use. See tr_inactvelimit
|
2010-07-23 01:19:13 +00:00
|
|
|
"seedRatioLimit" | double torrent-level seeding ratio
|
2009-09-25 21:05:59 +00:00
|
|
|
"seedRatioMode" | number which ratio to use. See tr_ratiolimit
|
2010-07-27 19:43:32 +00:00
|
|
|
"trackerAdd" | array strings of URLs to add
|
|
|
|
|
"trackerRemove" | array strings of URLs to remove
|
|
|
|
|
"trackerReplace" | array pairs of old/new announce URLs
|
2010-07-04 06:07:21 +00:00
|
|
|
"uploadLimit" | number maximum upload speed (KBps)
|
2009-09-25 21:05:59 +00:00
|
|
|
"uploadLimited" | boolean true if "uploadLimit" is honored
|
2008-06-17 16:25:13 +00:00
|
|
|
|
2008-08-26 15:27:00 +00:00
|
|
|
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".
|
|
|
|
|
|
2008-06-17 16:25:13 +00:00
|
|
|
Response arguments: none
|
2008-06-16 22:11:50 +00:00
|
|
|
|
2008-06-17 16:25:13 +00:00
|
|
|
3.3. Torrent Accessors
|
2008-06-16 22:11:50 +00:00
|
|
|
|
2008-06-17 16:25:13 +00:00
|
|
|
Method name: "torrent-get".
|
2008-06-16 22:11:50 +00:00
|
|
|
|
2008-06-17 16:25:13 +00:00
|
|
|
Request arguments:
|
2008-06-16 03:47:50 +00:00
|
|
|
|
2010-07-23 01:19:13 +00:00
|
|
|
(1) An optional "ids" array as described in 3.1.
|
2008-07-26 14:47:07 +00:00
|
|
|
(2) A required "fields" array of keys. (see list below)
|
2008-06-17 16:25:13 +00:00
|
|
|
|
2008-06-17 16:35:33 +00:00
|
|
|
Response arguments:
|
2008-06-17 16:25:13 +00:00
|
|
|
|
2008-07-26 14:47:07 +00:00
|
|
|
(1) A "torrents" array of objects, each of which contains
|
|
|
|
|
the key/value pairs matching the request's "fields" argument.
|
2009-04-04 05:29:08 +00:00
|
|
|
(2) If the request's "ids" field was "recently-active",
|
|
|
|
|
a "removed" array of torrent-id numbers of recently-removed
|
|
|
|
|
torrents.
|
2008-07-26 14:47:07 +00:00
|
|
|
|
2010-07-03 00:25:22 +00:00
|
|
|
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.
|
|
|
|
|
|
2009-09-25 21:05:59 +00:00
|
|
|
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
|
|
|
|
|
error | number | tr_stat
|
|
|
|
|
errorString | string | tr_stat
|
|
|
|
|
eta | number | tr_stat
|
|
|
|
|
files | array (see below) | n/a
|
|
|
|
|
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
|
2010-04-02 17:57:25 +00:00
|
|
|
isFinished | boolean | tr_stat
|
2009-09-25 21:05:59 +00:00
|
|
|
isPrivate | boolean | tr_torrent
|
|
|
|
|
leftUntilDone | number | tr_stat
|
2009-12-03 15:23:43 +00:00
|
|
|
magnetLink | number | n/a
|
2009-09-25 21:05:59 +00:00
|
|
|
manualAnnounceTime | number | tr_stat
|
|
|
|
|
maxConnectedPeers | number | tr_torrent
|
2009-12-03 12:40:23 +00:00
|
|
|
metadataPercentComplete | double | tr_stat
|
2009-09-25 21:05:59 +00:00
|
|
|
name | string | tr_info
|
|
|
|
|
peer-limit | number | tr_torrent
|
|
|
|
|
peers | array (see below) | n/a
|
|
|
|
|
peersConnected | number | tr_stat
|
|
|
|
|
peersFrom | object (see below) | n/a
|
|
|
|
|
peersGettingFromUs | number | tr_stat
|
|
|
|
|
peersKnown | number | tr_stat
|
|
|
|
|
peersSendingToUs | number | tr_stat
|
|
|
|
|
percentDone | double | tr_stat
|
|
|
|
|
pieces | string (see below) | tr_torrent
|
|
|
|
|
pieceCount | number | tr_info
|
|
|
|
|
pieceSize | number | tr_info
|
|
|
|
|
priorities | array (see below) | n/a
|
2010-07-23 01:38:34 +00:00
|
|
|
rateDownload (KBps) | double | tr_stat
|
|
|
|
|
rateUpload (KBps) | double | tr_stat
|
2009-09-25 21:05:59 +00:00
|
|
|
recheckProgress | double | tr_stat
|
2010-07-24 02:57:39 +00:00
|
|
|
seedIdleLimit | number | tr_torrent
|
|
|
|
|
seedIdleMode | number | tr_inactvelimit
|
2009-09-25 21:05:59 +00:00
|
|
|
seedRatioLimit | double | tr_torrent
|
|
|
|
|
seedRatioMode | number | tr_ratiolimit
|
|
|
|
|
sizeWhenDone | number | tr_stat
|
|
|
|
|
startDate | number | tr_stat
|
|
|
|
|
status | number | tr_stat
|
|
|
|
|
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: |
|
|
|
|
|
+-------------------------+------------+
|
|
|
|
|
| key | type |
|
|
|
|
|
| bytesCompleted | number | tr_torrent
|
|
|
|
|
| length | number | tr_info
|
|
|
|
|
| name | string | tr_info
|
|
|
|
|
-------------------+--------------------------------------+
|
|
|
|
|
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
|
|
|
|
|
-------------------+--------------------------------------+
|
|
|
|
|
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
|
2010-06-26 17:48:27 +00:00
|
|
|
| flagStr | string | tr_peer_stat
|
2009-09-25 21:05:59 +00:00
|
|
|
| isDownloadingFrom | boolean | tr_peer_stat
|
|
|
|
|
| isEncrypted | boolean | tr_peer_stat
|
|
|
|
|
| isIncoming | boolean | tr_peer_stat
|
|
|
|
|
| isUploadingTo | boolean | tr_peer_stat
|
|
|
|
|
| peerIsChoked | boolean | tr_peer_stat
|
|
|
|
|
| peerIsInterested | boolean | tr_peer_stat
|
|
|
|
|
| port | number | tr_peer_stat
|
|
|
|
|
| progress | double | tr_peer_stat
|
2010-07-23 01:38:34 +00:00
|
|
|
| rateToClient (KBps) | double | tr_peer_stat
|
|
|
|
|
| rateToPeer (KBps) | double | tr_peer_stat
|
2009-09-25 21:05:59 +00:00
|
|
|
-------------------+--------------------------------------+
|
|
|
|
|
peersFrom | an object containing: |
|
|
|
|
|
+-------------------------+------------+
|
|
|
|
|
| fromCache | number | tr_stat
|
2010-01-14 00:25:03 +00:00
|
|
|
| fromDht | number | tr_stat
|
2009-09-25 21:05:59 +00:00
|
|
|
| fromIncoming | number | tr_stat
|
2010-01-14 00:25:03 +00:00
|
|
|
| fromLtep | number | tr_stat
|
2009-09-25 21:05:59 +00:00
|
|
|
| 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: |
|
|
|
|
|
+-------------------------+------------+
|
2010-01-13 22:40:07 +00:00
|
|
|
| announce | string | tr_tracker_info
|
|
|
|
|
| scrape | string | tr_tracker_info
|
|
|
|
|
| tier | number | tr_tracker_info
|
|
|
|
|
| id | number | tr_tracker_info
|
2009-09-25 21:05:59 +00:00
|
|
|
-------------------+--------------------------------------+
|
|
|
|
|
trackerStats | array of objects, each containing: |
|
|
|
|
|
+-------------------------+------------+
|
2009-09-26 03:36:58 +00:00
|
|
|
| announce | string | tr_tracker_stat
|
2009-10-09 21:30:34 +00:00
|
|
|
| announceState | number | tr_tracker_stat
|
2009-09-25 21:05:59 +00:00
|
|
|
| downloadCount | number | tr_tracker_stat
|
|
|
|
|
| hasAnnounced | boolean | tr_tracker_stat
|
|
|
|
|
| hasScraped | boolean | tr_tracker_stat
|
|
|
|
|
| host | string | tr_tracker_stat
|
2010-01-13 22:46:22 +00:00
|
|
|
| id | number | tr_tracker_stat
|
2009-10-10 00:17:00 +00:00
|
|
|
| isBackup | boolean | tr_tracker_stat
|
2009-09-25 21:05:59 +00:00
|
|
|
| lastAnnouncePeerCount | number | tr_tracker_stat
|
|
|
|
|
| lastAnnounceResult | number | tr_tracker_stat
|
|
|
|
|
| lastAnnounceStartTime | number | tr_tracker_stat
|
|
|
|
|
| lastAnnounceSucceeded | boolean | tr_tracker_stat
|
|
|
|
|
| lastAnnounceTime | number | tr_tracker_stat
|
2010-02-05 05:16:18 +00:00
|
|
|
| lastAnnounceTimedOut | boolean | tr_tracker_stat
|
2009-09-25 21:05:59 +00:00
|
|
|
| lastScrapeResult | string | tr_tracker_stat
|
|
|
|
|
| lastScrapeStartTime | number | tr_tracker_stat
|
|
|
|
|
| lastScrapeSucceeded | boolean | tr_tracker_stat
|
|
|
|
|
| lastScrapeTime | number | tr_tracker_stat
|
2010-02-25 23:06:05 +00:00
|
|
|
| lastScrapeTimedOut | boolean | tr_tracker_stat
|
2009-09-25 21:05:59 +00:00
|
|
|
| leecherCount | number | tr_tracker_stat
|
|
|
|
|
| nextAnnounceTime | number | tr_tracker_stat
|
|
|
|
|
| nextScrapeTime | number | tr_tracker_stat
|
2009-10-09 21:30:34 +00:00
|
|
|
| scrapeState | number | tr_tracker_stat
|
2009-09-25 21:05:59 +00:00
|
|
|
| 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
|
|
|
|
|
+-------------------------+------------+
|
2008-06-16 03:47:50 +00:00
|
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
2008-06-17 16:25:13 +00:00
|
|
|
Say we want to get the name and total size of torrents #7 and #10.
|
2008-06-16 03:47:50 +00:00
|
|
|
|
|
|
|
|
Request:
|
2008-05-10 14:29:59 +00:00
|
|
|
|
|
|
|
|
{
|
2008-06-16 03:47:50 +00:00
|
|
|
"arguments": {
|
2009-02-10 18:19:09 +00:00
|
|
|
"fields": [ "id", "name", "totalSize" ],
|
|
|
|
|
"ids": [ 7, 10 ]
|
2008-08-19 16:36:59 +00:00
|
|
|
},
|
2008-06-17 16:25:13 +00:00
|
|
|
"method": "torrent-get",
|
2008-05-13 17:31:09 +00:00
|
|
|
"tag": 39693
|
2008-05-10 14:29:59 +00:00
|
|
|
}
|
|
|
|
|
|
2008-06-16 03:47:50 +00:00
|
|
|
|
|
|
|
|
Response:
|
2008-05-10 14:29:59 +00:00
|
|
|
|
|
|
|
|
{
|
2008-05-12 23:51:17 +00:00
|
|
|
"arguments": {
|
2008-06-17 16:25:13 +00:00
|
|
|
"torrents": [
|
2008-05-18 16:44:30 +00:00
|
|
|
{
|
2008-07-26 14:47:07 +00:00
|
|
|
"id": 10,
|
2008-06-16 03:47:50 +00:00
|
|
|
"name": "Fedora x86_64 DVD",
|
2010-01-16 22:41:01 +00:00
|
|
|
"totalSize": 34983493932,
|
2008-08-19 16:36:59 +00:00
|
|
|
},
|
2008-06-16 22:11:50 +00:00
|
|
|
{
|
2008-07-26 14:47:07 +00:00
|
|
|
"id": 7,
|
2008-06-16 22:11:50 +00:00
|
|
|
"name": "Ubuntu x86_64 DVD",
|
|
|
|
|
"totalSize", 9923890123,
|
2008-08-19 16:36:59 +00:00
|
|
|
}
|
2008-05-18 16:44:30 +00:00
|
|
|
]
|
2008-06-16 22:11:50 +00:00
|
|
|
},
|
|
|
|
|
"result": "success",
|
|
|
|
|
"tag": 39693
|
2008-05-10 14:29:59 +00:00
|
|
|
}
|
|
|
|
|
|
2008-06-17 16:35:33 +00:00
|
|
|
3.4. Adding a Torrent
|
2008-05-10 14:29:59 +00:00
|
|
|
|
2008-05-12 23:51:17 +00:00
|
|
|
Method name: "torrent-add"
|
|
|
|
|
|
2008-05-10 16:38:42 +00:00
|
|
|
Request arguments:
|
2008-05-10 14:29:59 +00:00
|
|
|
|
2010-02-02 07:48:03 +00:00
|
|
|
key | value type & description
|
|
|
|
|
---------------------+-------------------------------------------------
|
|
|
|
|
"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)
|
2008-05-10 14:29:59 +00:00
|
|
|
|
2008-08-13 16:57:12 +00:00
|
|
|
Either "filename" OR "metainfo" MUST be included.
|
2008-05-20 17:33:54 +00:00
|
|
|
All other arguments are optional.
|
2008-05-10 14:29:59 +00:00
|
|
|
|
2008-05-12 13:05:06 +00:00
|
|
|
Response arguments: on success, a "torrent-added" object in the
|
2008-06-16 03:47:50 +00:00
|
|
|
form of one of 3.3's tr_info objects with the
|
|
|
|
|
fields for id, name, and hashString.
|
2008-05-10 14:29:59 +00:00
|
|
|
|
2008-12-09 17:01:49 +00:00
|
|
|
3.5. Removing a Torrent
|
|
|
|
|
|
|
|
|
|
Method name: "torrent-remove"
|
|
|
|
|
|
|
|
|
|
Request arguments:
|
|
|
|
|
|
|
|
|
|
string | value type & description
|
|
|
|
|
---------------------------+-------------------------------------------------
|
|
|
|
|
"ids" | array torrent list, as described in 3.1
|
2009-04-05 17:52:21 +00:00
|
|
|
"delete-local-data" | boolean delete local data. (default: false)
|
2008-12-09 17:01:49 +00:00
|
|
|
|
|
|
|
|
Response arguments: none
|
|
|
|
|
|
2008-06-18 22:01:15 +00:00
|
|
|
|
2009-05-13 15:54:04 +00:00
|
|
|
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
|
2009-05-21 20:56:45 +00:00
|
|
|
"location" | string the new torrent location
|
|
|
|
|
"move" | boolean if true, move from previous location.
|
|
|
|
|
| otherwise, search "location" for files
|
2009-05-13 15:54:04 +00:00
|
|
|
|
|
|
|
|
Response arguments: none
|
|
|
|
|
|
|
|
|
|
|
2008-06-18 22:01:15 +00:00
|
|
|
4. Session Requests
|
2008-05-10 14:29:59 +00:00
|
|
|
|
2008-05-10 16:38:42 +00:00
|
|
|
4.1. Session Arguments
|
2008-05-10 14:29:59 +00:00
|
|
|
|
2010-07-23 01:19:13 +00:00
|
|
|
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-enabled" | boolean true means enabled
|
|
|
|
|
"blocklist-size" | number number of rules in the blocklist
|
|
|
|
|
"cache-size" | 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
|
|
|
|
|
"dht-enabled" | boolean true means allow dht in public torrents
|
|
|
|
|
"encryption" | string "required", "preferred", "tolerated"
|
|
|
|
|
"inactive-seeding-limit" | number the default seed inactivity limit for torrents to use
|
|
|
|
|
"inactive-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
|
|
|
|
|
"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
|
|
|
|
|
"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
|
|
|
|
|
"version" | string long version string "$version ($revision)"
|
2009-01-16 01:03:33 +00:00
|
|
|
|
|
|
|
|
"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.
|
2008-05-10 14:29:59 +00:00
|
|
|
|
2008-06-18 22:01:15 +00:00
|
|
|
4.1.1. Mutators
|
2008-05-10 16:38:42 +00:00
|
|
|
|
2008-05-12 23:51:17 +00:00
|
|
|
Method name: "session-set"
|
2009-03-26 18:06:54 +00:00
|
|
|
Request arguments: one or more of 4.1's arguments, except: "blocklist-size",
|
2010-02-02 18:27:57 +00:00
|
|
|
"config-dir", "rpc-version", "rpc-version-minimum",
|
|
|
|
|
and "version"
|
2008-05-10 16:38:42 +00:00
|
|
|
Response arguments: none
|
|
|
|
|
|
2008-06-18 22:01:15 +00:00
|
|
|
4.1.2. Accessors
|
2008-05-10 14:29:59 +00:00
|
|
|
|
2008-05-12 23:51:17 +00:00
|
|
|
Method name: "session-get"
|
2008-05-10 14:29:59 +00:00
|
|
|
Request arguments: none
|
2008-05-10 22:14:19 +00:00
|
|
|
Response arguments: all of 4.1's arguments
|
2008-05-10 14:29:59 +00:00
|
|
|
|
2008-06-18 22:01:15 +00:00
|
|
|
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
|
2009-01-19 21:17:29 +00:00
|
|
|
---------------------------+-------------------------------+
|
|
|
|
|
"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
|
2009-04-03 23:21:40 +00:00
|
|
|
|
|
|
|
|
4.3. Blocklist
|
|
|
|
|
|
|
|
|
|
Method name: "blocklist-update"
|
|
|
|
|
Request arguments: none
|
2009-04-06 16:36:00 +00:00
|
|
|
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"
|
2008-06-18 22:01:15 +00:00
|
|
|
|
2009-01-16 01:03:33 +00:00
|
|
|
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"
|
2009-03-04 19:52:57 +00:00
|
|
|
| | yes | torrent-get | new arg "downloaders"
|
|
|
|
|
| | yes | session-get | new arg "version"
|
|
|
|
|
| | yes | torrent-remove | new method
|
2009-01-16 01:03:33 +00:00
|
|
|
------+---------+-----------+----------------+-------------------------------
|
|
|
|
|
4 | 1.50 | yes | session-get | new arg "rpc-version"
|
2009-03-04 19:52:57 +00:00
|
|
|
| | 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"
|
2009-01-16 01:03:33 +00:00
|
|
|
------+---------+-----------+----------------+-------------------------------
|
2009-04-19 17:02:27 +00:00
|
|
|
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"
|
2009-03-28 16:47:01 +00:00
|
|
|
| | yes | session-get | new arg "alt-speed-enabled"
|
2009-04-19 17:02:27 +00:00
|
|
|
| | yes | session-get | new arg "alt-speed-end"
|
2009-03-28 16:47:01 +00:00
|
|
|
| | yes | session-get | new arg "alt-speed-time-enabled"
|
|
|
|
|
| | yes | session-get | new arg "alt-speed-up"
|
2009-03-25 19:18:00 +00:00
|
|
|
| | yes | session-get | new arg "blocklist-enabled"
|
2009-03-26 18:06:54 +00:00
|
|
|
| | yes | session-get | new arg "blocklist-size"
|
2009-03-25 19:18:00 +00:00
|
|
|
| | yes | session-get | new arg "peer-limit-per-torrent"
|
2009-04-19 17:02:27 +00:00
|
|
|
| | 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"
|
2009-03-29 18:45:35 +00:00
|
|
|
| | yes | torrent-get | new arg "seedRatioLimit"
|
|
|
|
|
| | yes | torrent-get | new arg "seedRatioMode"
|
2009-04-02 22:59:30 +00:00
|
|
|
| | yes | torrent-get | new arg "torrentFile"
|
2009-03-28 16:47:01 +00:00
|
|
|
| | yes | torrent-get | new ids option "recently-active"
|
2009-03-04 19:52:57 +00:00
|
|
|
| | NO | torrent-get | removed arg "downloadLimitMode"
|
|
|
|
|
| | NO | torrent-get | removed arg "uploadLimitMode"
|
2009-03-02 05:48:32 +00:00
|
|
|
------+---------+-----------+----------------+-------------------------------
|
2009-05-19 18:32:14 +00:00
|
|
|
6 | 1.70 | yes | | new "method torrent-set-location"
|
2009-05-13 15:54:04 +00:00
|
|
|
------+---------+-----------+----------------+-------------------------------
|
2009-09-25 21:05:59 +00:00
|
|
|
7 | 1.80 | NO | torrent-get | removed arg "announceResponse"
|
|
|
|
|
| | NO | torrent-get | removed arg "announceURL"
|
2009-09-26 06:20:33 +00:00
|
|
|
| | NO | torrent-get | removed arg "downloaders"
|
2009-09-25 21:05:59 +00:00
|
|
|
| | NO | torrent-get | removed arg "lastAnnounceTime"
|
|
|
|
|
| | NO | torrent-get | removed arg "lastScrapeTime"
|
2009-09-26 06:20:33 +00:00
|
|
|
| | NO | torrent-get | removed arg "leechers"
|
2009-09-25 21:05:59 +00:00
|
|
|
| | NO | torrent-get | removed arg "nextAnnounceTime"
|
|
|
|
|
| | NO | torrent-get | removed arg "nextScrapeTime"
|
|
|
|
|
| | NO | torrent-get | removed arg "scrapeResponse"
|
|
|
|
|
| | NO | torrent-get | removed arg "scrapeURL"
|
2009-09-26 06:20:33 +00:00
|
|
|
| | NO | torrent-get | removed arg "seeders"
|
|
|
|
|
| | NO | torrent-get | removed arg "timesCompleted"
|
2009-11-22 01:16:27 +00:00
|
|
|
| | NO | torrent-get | removed arg "swarmSpeed"
|
2009-12-03 15:23:43 +00:00
|
|
|
| | yes | torrent-get | new arg "magnetLink"
|
2009-12-03 12:40:23 +00:00
|
|
|
| | yes | torrent-get | new arg "metadataPercentComplete"
|
2009-10-19 05:25:50 +00:00
|
|
|
| | yes | torrent-get | new arg "trackerStats"
|
|
|
|
|
| | yes | session-set | new arg "incomplete-dir"
|
|
|
|
|
| | yes | session-set | new arg "incomplete-dir-enabled"
|
2010-02-01 04:43:10 +00:00
|
|
|
------+---------+-----------+----------------+-------------------------------
|
|
|
|
|
8 | 1.90 | yes | session-set | new arg "rename-partial-files"
|
|
|
|
|
| | yes | session-get | new arg "rename-partial-files"
|
2010-02-02 18:27:57 +00:00
|
|
|
| | yes | session-get | new arg "config-dir"
|
2010-02-02 07:48:03 +00:00
|
|
|
| | yes | torrent-add | new arg "bandwidthPriority"
|
2010-02-05 05:16:18 +00:00
|
|
|
| | yes | torrent-get | new trackerStats arg "lastAnnounceTimedOut"
|
2010-02-25 23:06:05 +00:00
|
|
|
------+---------+-----------+----------------+-------------------------------
|
|
|
|
|
8 | 1.92 | yes | torrent-get | new trackerStats arg "lastScrapeTimedOut"
|
2010-03-17 19:23:03 +00:00
|
|
|
------+---------+-----------+----------------+-------------------------------
|
|
|
|
|
9 | 2.00 | yes | session-set | new arg "start-added-torrents"
|
2010-07-03 00:25:22 +00:00
|
|
|
| | 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"
|
2010-06-30 05:52:24 +00:00
|
|
|
------+---------+-----------+----------------+-------------------------------
|
2010-07-04 06:07:21 +00:00
|
|
|
10 | 2.10 | yes | session-get | new arg "cache-size"
|
2010-07-03 00:25:22 +00:00
|
|
|
| | yes | session-set | new arg "trash-original-torrent-files"
|
|
|
|
|
| | yes | session-get | new arg "trash-original-torrent-files"
|
|
|
|
|
| | yes | torrent-get | new arg "isFinished"
|
|
|
|
|
| | yes | torrent-set | new arg "trackerAdd"
|
|
|
|
|
| | yes | torrent-set | new arg "trackerEdit"
|
|
|
|
|
| | yes | torrent-set | new arg "trackerRemove"
|
2010-07-23 01:19:13 +00:00
|
|
|
| | yes | session-set | new arg "inactive-seeding-limit"
|
|
|
|
|
| | yes | session-set | new arg "inactive-seeding-limit-enabled"
|
|
|
|
|
| | yes | session-get | new arg "inactive-seeding-limit"
|
|
|
|
|
| | yes | session-get | new arg "inactive-seeding-limit-enabled"
|
2010-07-24 02:57:39 +00:00
|
|
|
| | yes | torrent-set | new arg "seedIdleLimit"
|
|
|
|
|
| | yes | torrent-set | new arg "seedIdleMode"
|
