mirror
/
transmission
mirror of https://github.com/transmission/transmission
1
0
Fork 0
Code Issues Releases Wiki Activity
transmission/docs/rpc-spec.md

987 lines
38 KiB
Markdown
Raw Normal View History

Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
# Transmission's RPC specification
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
This document describes a protocol for interacting with Transmission sessions remotely.
### 1.1 Terminology
The [JSON](https://www.json.org/) terminology in [RFC 4627](https://datatracker.ietf.org/doc/html/rfc4627) is used.
RPC requests and responses are formatted in JSON.
### 1.2 Tools
Fix typographical errors in the documentation. (#2889)
2022-04-06 22:20:38 +00:00
If `transmission-remote` is called with a `--debug` argument, its RPC traffic to the Transmission server will be dumped to the terminal. This can be useful when you want to compare requests in your application to another for reference.
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
If `transmission-qt` is run with an environment variable `TR_RPC_VERBOSE` set, it too will dump the RPC requests and responses to the terminal for inspection.
Lastly, using devtools in the Transmission web client is always an option.
Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
## 2 Message format
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
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.
Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
### 2.1 Requests
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
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. The keys allowed are defined by the `method`.
3. An optional `tag` number used by clients to track responses. If provided by a request, the response MUST include the same tag.
```json
{
"arguments": {
"fields": [
"version"
]
},
"method": "session-get",
"tag": 912313
}
```
Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
### 2.2 Responses
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
Responses to a request will include:
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. Its keys contents are defined by the `method` and `arguments` of the original request.
3. An optional `tag` number as described in 2.1.
```json
{
"arguments": {
"version": "2.93 (3c5870d4f5)"
},
"result": "success",
"tag": 912313
}
```
Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
### 2.3 Transport mechanism
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
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.
Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
#### 2.3.1 CSRF protection
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
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.
Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
#### 2.3.2 DNS rebinding protection
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
Additional check is being made on each RPC request to make sure that the
client sending the request does so using one of the allowed hostnames by
which RPC server is meant to be available.
If host whitelisting is enabled (which is true by default), Transmission
inspects the `Host:` HTTP header value (with port stripped, if any) and
matches it to one of the whitelisted names. Regardless of host whitelist
content, `localhost` and `localhost.` domain names as well as all the IP
addresses are always implicitly allowed.
For more information on configuration, see settings.json documentation for
`rpc-host-whitelist-enabled` and `rpc-host-whitelist` keys.
Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
#### 2.3.3 Authentication
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
Enabling authentication is an optional security feature that can be enabled
on Transmission RPC servers. Authentication occurs by method of HTTP Basic
Access Authentication.
If authentication is enabled, Transmission inspects the `Authorization:`
HTTP header value to validate the credentials of the request. The value
of this HTTP header is expected to be [`Basic <b64 credentials>`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization#basic),
where <b64 credentials> is equal to a base64 encoded string of the
username and password (respectively), separated by a colon.
Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
## 3 Torrent requests
### 3.1 Torrent action requests
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
| 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
Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
2. a list of torrent id numbers, SHA1 hash strings, or both
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
3. a string, `recently-active`, for recently-active torrents
Response arguments: none
Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
### 3.2 Torrent mutator: `torrent-set`
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
Method name: `torrent-set`
Request arguments:
| Key | Value Type | Value Description
|:--|:--|:--
| `bandwidthPriority` | number | this torrent's bandwidth tr_priority_t
| `downloadLimit` | number | maximum download speed (KBps)
| `downloadLimited` | boolean | true if `downloadLimit` is honored
| `files-unwanted` | array | indices of file(s) to not download
feat: add tr_torrentSetTrackerList(), tr_torrentGetTrackerList() (#2642) Add a getter/setter for torrent announce URLs as text that can be copied and pasted: one URL per line, with a blank line between tiers. C API: tr_torrentGetTrackerList() and tr_torrentSetTrackerList() RPC APi: `trackerList` in `torrent-get` and `torrent-set`. This deprecates `trackerAdd`, `trackerRemove`, and `trackerEdit` from the RPC API.
2022-02-18 17:52:01 +00:00
| `files-wanted` | array | indices of file(s) to download
Limit bandwidth used by a group of torrents (#2761) * Add support for bandwidth groups. i.e. Bandwidth limit for a (user specified) group of torrents,
2022-03-18 13:11:59 +00:00
| `group` | string | The name of this torrent's bandwidth group
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
| `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
docs: un-deprecate trackerAdd RPC (#3237) Fixes #3226.
2022-06-09 00:52:37 +00:00
| `trackerAdd` | array | add a new tracker URL in its own new tier
| `trackerList` | string | rebuild the torrent's tracker list with a string of announce URLs, one per line, with a blank line between tiers
| `trackerRemove` | array | remove a tracker URL
| `trackerReplace` | array | modify a tracker URL
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
| `uploadLimit` | number | maximum upload speed (KBps)
| `uploadLimited` | boolean | true if `uploadLimit` is honored
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
Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
### 3.3 Torrent accessor: `torrent-get`
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
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.
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](../libtransmission/transmission.h).
The 'source' column here corresponds to the data structure there.
| Key | Value Type | transmission.h source
|:--|:--|:--
| `activityDate` | number | tr_stat
| `addedDate` | number | tr_stat
feat: add rpc torrentGet.availability (#3252)
2022-06-11 17:06:07 +00:00
| `availability` | array (see below)| tr_torrentAvailability()
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
| `bandwidthPriority` | number | tr_priority_t
| `comment` | string | tr_torrent_view
| `corruptEver`| number | tr_stat
| `creator`| string | tr_torrent_view
| `dateCreated`| number| tr_torrent_view
| `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
| `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
| `fileStats`| array (see below)| n/a
Limit bandwidth used by a group of torrents (#2761) * Add support for bandwidth groups. i.e. Bandwidth limit for a (user specified) group of torrents,
2022-03-18 13:11:59 +00:00
| `group`| string| n/a
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
| `hashString`| string| tr_torrent_view
| `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 of strings | tr_torrent
| `leftUntilDone` | number| tr_stat
| `magnetLink` | string| n/a
| `manualAnnounceTime` | number| tr_stat
| `maxConnectedPeers` | number| tr_torrent
| `metadataPercentComplete` | double| tr_stat
| `name` | string| tr_torrent_view
| `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
| `peersSendingToUs` | number| tr_stat
Add support for torrent-get calls with the key percentComplete (#2615) Co-authored-by: Michael Hadam <michael@hadam.us>
2022-02-13 07:27:47 +00:00
| `percentComplete` | double | tr_stat
| `percentDone` | double | tr_stat
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
| `pieces` | string (see below)| tr_torrent
| `pieceCount`| number| tr_torrent_view
| `pieceSize`| number| tr_torrent_view
| `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 (see below)| tr_stat
| `trackers`| array (see below)| n/a
feat: add tr_torrentSetTrackerList(), tr_torrentGetTrackerList() (#2642) Add a getter/setter for torrent announce URLs as text that can be copied and pasted: one URL per line, with a blank line between tiers. C API: tr_torrentGetTrackerList() and tr_torrentSetTrackerList() RPC APi: `trackerList` in `torrent-get` and `torrent-set`. This deprecates `trackerAdd`, `trackerRemove`, and `trackerEdit` from the RPC API.
2022-02-18 17:52:01 +00:00
' `trackerList` | string | string of announce URLs, one per line, with a blank line between tiers
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
| `trackerStats`| array (see below)| n/a
| `totalSize`| number| tr_torrent_view
| `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 of strings | tr_tracker_view
| `webseedsSendingToUs`| number| tr_stat
feat: add rpc torrentGet.availability (#3252)
2022-06-11 17:06:07 +00:00
`availability`: An array of `pieceCount` numbers representing the number of connected peers that have each piece, or -1 if we already have the piece ourselves.
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
`files`: array of objects, each containing:
| Key | Value Type | transmission.h source
|:--|:--|:--
| `bytesCompleted` | number | tr_file_view
| `length` | number | tr_file_view
| `name` | string | tr_file_view
`fileStats`: a file's non-constant properties. An array of `tr_info.filecount` objects, each containing:
| Key | Value Type | transmission.h source
|:--|:--|:--
| `bytesCompleted` | number | tr_file_view
| `wanted` | boolean | tr_file_view
| `priority` | number | tr_file_view
`peers`: an array of objects, each containing:
| Key | Value Type | transmission.h source
|:--|:--|:--
| `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:
| Key | Value Type | transmission.h source
|:--|:--|:--
| `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 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. (Source: tr_torrent)
`priorities`: An array of `tr_torrentFileCount()` numbers. Each is the `tr_priority_t` mode for the corresponding file.
`status`: A number between 0 and 6, where:
| Value | Meaning
|:--|:--
| 0 | Torrent is stopped
| 1 | Torrent is queued to verify local data
| 2 | Torrent is verifying local data
| 3 | Torrent is queued to download
| 4 | Torrent is downloading
| 5 | Torrent is queued to seed
| 6 | Torrent is seeding
`trackers`: array of objects, each containing:
| Key | Value Type | transmission.h source
|:--|:--|:--
feat: use libpsl (#2575) Use libpsl to calculate public and private parts of URL hosts.
2022-02-12 17:30:27 +00:00
| `announce` | string | tr_tracker_view
| `id` | number | tr_tracker_view
| `scrape` | string | tr_tracker_view
| `sitename` | string | tr_tracker_view
| `tier` | number | tr_tracker_view
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
`trackerStats`: array of objects, each containing:
| Key | Value Type | transmission.h source
|:--|:--|:--
feat: use libpsl (#2575) Use libpsl to calculate public and private parts of URL hosts.
2022-02-12 17:30:27 +00:00
| `announceState` | number | tr_tracker_view
| `announce` | string | tr_tracker_view
| `downloadCount` | number | tr_tracker_view
| `hasAnnounced` | boolean | tr_tracker_view
| `hasScraped` | boolean | tr_tracker_view
| `host` | string | tr_tracker_view
| `id` | number | tr_tracker_view
| `isBackup` | boolean | tr_tracker_view
| `lastAnnouncePeerCount` | number | tr_tracker_view
| `lastAnnounceResult` | string | tr_tracker_view
| `lastAnnounceStartTime` | number | tr_tracker_view
| `lastAnnounceSucceeded` | boolean | tr_tracker_view
| `lastAnnounceTime` | number | tr_tracker_view
| `lastAnnounceTimedOut` | boolean | tr_tracker_view
| `lastScrapeResult` | string | tr_tracker_view
| `lastScrapeStartTime` | number | tr_tracker_view
| `lastScrapeSucceeded` | boolean | tr_tracker_view
| `lastScrapeTime` | number | tr_tracker_view
| `lastScrapeTimedOut` | boolean | tr_tracker_view
| `leecherCount` | number | tr_tracker_view
| `nextAnnounceTime` | number | tr_tracker_view
| `nextScrapeTime` | number | tr_tracker_view
| `scrapeState` | number | tr_tracker_view
| `scrape` | string | tr_tracker_view
| `seederCount` | number | tr_tracker_view
| `sitename` | string | tr_tracker_view
| `tier` | number | tr_tracker_view
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
`wanted`: An array of `tr_torrentFileCount()` booleans true if the corresponding file is to be downloaded. (Source: `tr_file_view`)
Example:
Say we want to get the name and total size of torrents #7 and #10.
Request:
```json
{
"arguments": {
"fields": [ "id", "name", "totalSize" ],
"ids": [ 7, 10 ]
},
"method": "torrent-get",
"tag": 39693
}
```
Response:
```json
{
"arguments": {
"torrents": [
{
"id": 10,
"name": "Fedora x86_64 DVD",
"totalSize": 34983493932
},
{
"id": 7,
"name": "Ubuntu x86_64 DVD",
"totalSize": 9923890123
}
]
},
"result": "success",
"tag": 39693
}
```
Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
### 3.4 Adding a torrent
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
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
| `labels` | array | array of string labels
| `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)
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. See [libcurl documentation](http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTCOOKIE) for more information.
Response arguments:
* On success, a `torrent-added` object in the form of one of 3.3's torrent objects with the fields for `id`, `name`, and `hashString`.
Clarify torrent-add result on duplicate torrents (#2690) Rewrote a sentence to ensure it's clear that a duplicate torrent error still returns a "success" result over RPC.
2022-02-23 03:59:48 +00:00
* When attempting to add a duplicate torrent, a `torrent-duplicate` object in the same form is returned, but the response's `result` value is still `success`.
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
### 3.5 Removing a torrent
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
Method name: `torrent-remove`
| Key | Value Type | Description
|:--|:--|:--
| `ids` | array | torrent list, as described in 3.1
| `delete-local-data` | boolean | delete local data. (default: false)
Response arguments: none
Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
### 3.6 Moving a torrent
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
Method name: `torrent-set-location`
Request arguments:
| Key | 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
Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
### 3.7 Renaming a torrent's path
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
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:
| Key | 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
Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
## 4 Session requests
### 4.1 Session arguments
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
| Key | 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-day` | number | what day(s) to turn on alt speeds (look at tr_sched_day)
| `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-up` | number | max global upload speed (KBps)
| `blocklist-enabled` | boolean | true means enabled
| `blocklist-size` | number | number of rules in the blocklist
| `blocklist-url` | string | location of the blocklist to use for `blocklist-update`
| `cache-size-mb` | number | maximum size of the disk cache (MB)
| `config-dir` | string | location of transmission's configuration directory
refactor: do not mix torrent, default trackers
2022-02-20 19:00:52 +00:00
| `default-trackers` | list of default trackers to use on public torrents
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
| `dht-enabled` | boolean | true means allow dht in public torrents
| `download-dir` | string | default path to download torrents
feat: add tr_torrentSetTrackerList(), tr_torrentGetTrackerList() (#2642) Add a getter/setter for torrent announce URLs as text that can be copied and pasted: one URL per line, with a blank line between tiers. C API: tr_torrentGetTrackerList() and tr_torrentSetTrackerList() RPC APi: `trackerList` in `torrent-get` and `torrent-set`. This deprecates `trackerAdd`, `trackerRemove`, and `trackerEdit` from the RPC API.
2022-02-18 17:52:01 +00:00
| `download-dir-free-space` | number | **DEPRECATED** Use the `free-space` method instead.
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
| `download-queue-enabled` | boolean | if true, limit how many torrents can be downloaded at once
| `download-queue-size` | number | max number of torrents to download at once (see download-queue-enabled)
| `encryption` | string | `required`, `preferred`, `tolerated`
| `idle-seeding-limit-enabled` | boolean | true if the seeding inactivity limit is honored by default
| `idle-seeding-limit` | number | torrents we're seeding will be stopped if they're idle for this long
| `incomplete-dir-enabled` | boolean | true means keep torrents in incomplete-dir until done
| `incomplete-dir` | string | path for incomplete torrents, when enabled
| `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
| `peer-port-random-on-start` | boolean | true means pick a random peer port on launch
| `peer-port` | number | port number
| `pex-enabled` | boolean | true means allow pex in public torrents
| `port-forwarding-enabled` | boolean | true means ask upstream router to forward the configured peer port to transmission using UPnP or NAT-PMP
| `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-minimum` | number | the minimum RPC API version supported
docs: fix documented type of rpc-version-semver (#3209)
2022-06-06 02:17:05 +00:00
| `rpc-version-semver` | string | the current RPC API version in a semver-compatible string
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
| `rpc-version` | number | the current RPC API version
feat: run script when done seeding (#2621) * feat: add seeding-done script to core and rpc * feat: add seeding-done script to gtk client * feat: add seeding-done script to qt client * feat: add seeding-done script to transmission-remote * refactor: make Qt and GTK client text match * test: update tests Co-authored-by: Timothy Nibeaudeau <timothy.nibeaudeau@gmail.com>
2022-02-14 04:07:12 +00:00
| `script-torrent-added-enabled` | boolean | whether or not to call the `added` script
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
| `script-torrent-added-filename` | string | filename of the script to run
| `script-torrent-done-enabled` | boolean | whether or not to call the `done` script
| `script-torrent-done-filename` | string | filename of the script to run
feat: run script when done seeding (#2621) * feat: add seeding-done script to core and rpc * feat: add seeding-done script to gtk client * feat: add seeding-done script to qt client * feat: add seeding-done script to transmission-remote * refactor: make Qt and GTK client text match * test: update tests Co-authored-by: Timothy Nibeaudeau <timothy.nibeaudeau@gmail.com>
2022-02-14 04:07:12 +00:00
| `script-torrent-done-seeding-enabled` | boolean | whether or not to call the `seeding-done` script
| `script-torrent-done-seeding-filename` | string | filename of the script to run
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
| `seed-queue-enabled` | boolean | if true, limit how many torrents can be uploaded at once
| `seed-queue-size` | number | max number of torrents to uploaded at once (see seed-queue-enabled)
| `seedRatioLimit` | double | the default seed ratio for torrents to use
| `seedRatioLimited` | boolean | true if seedRatioLimit is honored by default
| `speed-limit-down-enabled` | boolean | true means enabled
| `speed-limit-down` | number | max global download speed (KBps)
| `speed-limit-up-enabled` | boolean | true means enabled
| `speed-limit-up` | number | max global upload speed (KBps)
| `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`: an object containing:
| Key | Value Type | transmission.h source
|:--|:--|:--
| `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)
`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.
Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
#### 4.1.1 Mutators
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
Method name: `session-set`
docs: fix documented type of rpc-version-semver (#3209)
2022-06-06 02:17:05 +00:00
Request arguments: the mutable properties from 4.1's arguments, i.e. all of them
except:
* `blocklist-size`
* `config-dir`
* `rpc-version-minimum`,
* `rpc-version-semver`
* `rpc-version`
* `session-id`
* `version`
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
Response arguments: none
Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
#### 4.1.2 Accessors
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
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.
Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
### 4.2 Session statistics
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
Method name: `session-stats`
Request arguments: none
Response arguments:
| Key | Value Type | Description
|:--|:--|:--
| `activeTorrentCount` | number
| `downloadSpeed` | number
| `pausedTorrentCount` | number
| `torrentCount` | number
| `uploadSpeed` | number
| `cumulative-stats` | stats object (see below)
| `current-stats` | stats object (see below)
A stats object contains:
| Key | Value Type | transmission.h source
|:--|:--|:--
| 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
Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
### 4.3 Blocklist
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
Method name: `blocklist-update`
Request arguments: none
Response arguments: a number `blocklist-size`
Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
### 4.4 Port checking
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
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`
Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
### 4.5 Session shutdown
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
This method tells the transmission session to shut down.
Method name: `session-close`
Request arguments: none
Response arguments: none
Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
### 4.6 Queue movement requests
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
| Method name | transmission.h source
|:--|:--
| `queue-move-top` | tr_torrentQueueMoveTop()
| `queue-move-up` | tr_torrentQueueMoveUp()
| `queue-move-down` | tr_torrentQueueMoveDown()
| `queue-move-bottom` | tr_torrentQueueMoveBottom()
Request arguments:
| Key | Value Type | Description
|:--|:--|:--
| `ids` | array | torrent list, as described in 3.1.
Response arguments: none
Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
### 4.7 Free space
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
This method tests how much free space is available in a
client-specified folder.
Method name: `free-space`
Request arguments:
| Key | Value type | Description
docs: convert some wiki markup to markdown (#2692)
2022-02-23 17:00:55 +00:00
|:--|:--|:--
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
| `path` | string | the directory to query
Response arguments:
| Key | Value type | Description
|:--|:--|:--
| `path` | string | same as the Request argument
| `size-bytes` | number | the size, in bytes, of the free space in that directory
| `total_size` | number | the total capacity, in bytes, of that directory
Limit bandwidth used by a group of torrents (#2761) * Add support for bandwidth groups. i.e. Bandwidth limit for a (user specified) group of torrents,
2022-03-18 13:11:59 +00:00
### 4.8 Bandwidth groups
Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
#### 4.8.1 Bandwidth group mutator: `group-set`
Limit bandwidth used by a group of torrents (#2761) * Add support for bandwidth groups. i.e. Bandwidth limit for a (user specified) group of torrents,
2022-03-18 13:11:59 +00:00
Method name: `group-set`
Request parameters:
| Key | Value type | Description
|:--|:--|:--
| `honorsSessionLimits` | boolean | true if session upload limits are honored
| `name` | string | Bandwidth group name
| `speed-limit-down-enabled` | boolean | true means enabled
| `speed-limit-down` | number | max global download speed (KBps)
| `speed-limit-up-enabled` | boolean | true means enabled
| `speed-limit-up` | number | max global upload speed (KBps)
Response arguments: none
Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
#### 4.8.2 Bandwidth group accessor: `group-get`
Limit bandwidth used by a group of torrents (#2761) * Add support for bandwidth groups. i.e. Bandwidth limit for a (user specified) group of torrents,
2022-03-18 13:11:59 +00:00
Method name: `group-get`
Request arguments: An optional argument `group`.
`group` is either a string naming the bandwidth group,
or a list of such strings.
If `group` is omitted, all bandwidth groups are used.
Response arguments:
| Key | Value type | Description
|:--|:--|:--
|`group`| array | A list of bandwidth group description objects
A bandwidth group description object has:
| Key | Value type | Description
|:--|:--|:--
| `honorsSessionLimits` | boolean | true if session upload limits are honored
| `name` | string | Bandwidth group name
| `speed-limit-down-enabled` | boolean | true means enabled
| `speed-limit-down` | number | max global download speed (KBps)
| `speed-limit-up-enabled` | boolean | true means enabled
| `speed-limit-up` | number | max global upload speed (KBps)
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
Improve the documentation (#2900) * Unify the line endings to the Unix style (LF only). * Fix (where possible) or remove broken links. * Improve the documentation. Fix or remove broken links (depending on whether I could find a working version of the resource). Change all links to use HTTPS instead of HTTP. Unify the capitalizations (e.g. uppercase abbreviations, capitalize proper names and downcase other words). Fix or improve some parts of the text, clarifying what is meant. Improve some parts of the program examples (e.g. only use root privileges where really required).
2022-04-11 17:38:32 +00:00
## 5 Protocol versions
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
This section lists the changes that have been made to the RPC protocol.
There are two ways to check for API compatibility. Since most developers know
semver, session-get's `rpc-version-semver` is the recommended way. That value
is a semver-compatible string of the RPC protocol version number.
Since Transmission predates the semver 1.0 spec, the previous scheme was for
the RPC version to be a whole number and to increment it whenever a change was
made. That is session-get's `rpc-version`. `rpc-version-minimum` lists the
oldest version that is compatible with the current version; i.e. an app coded
to use `rpc-version-minimum` would still work on a Transmission release running
`rpc-version`.
Breaking changes are denoted with a :bomb: emoji.
Transmission 1.30 (`rpc-version-semver` 1.0.0, `rpc-version`: 1)
Initial revision.
Transmission 1.40 (`rpc-version-semver` 1.1.0, `rpc-version`: 2)
| Method | Description
|:---|:---
| `torrent-get` | new `port` to `peers`
Transmission 1.41 (`rpc-version-semver` 1.2.0, `rpc-version`: 3)
| Method | Description
|:---|:---
| `session-get` | new arg `version`
| `torrent-get` | new arg `downloaders`
| `torrent-remove` | new method
Transmission 1.50 (`rpc-version-semver` 1.3.0, `rpc-version`: 4)
| Method | Description
|:---|:---
|`session-get` | new arg `rpc-version-minimum`
|`session-get` | new arg `rpc-version`
|`session-stats` | added `cumulative-stats`
|`session-stats` | added `current-stats`
|`torrent-get` | new arg `downloadDir`
Transmission 1.60 (`rpc-version-semver` 2.0.0, `rpc-version`: 5)
| Method | Description
|:---|:---
| `session-get` | :bomb: renamed `peer-limit` to `peer-limit-global`
| `session-get` | :bomb: renamed `pex-allowed` to `pex-enabled`
| `session-get` | :bomb: renamed `port` to `peer-port`
| `torrent-get` | :bomb: removed arg `downloadLimitMode`
| `torrent-get` | :bomb: removed arg `uploadLimitMode`
| `torrent-set` | :bomb: renamed `speed-limit-down-enabled` to `downloadLimited`
| `torrent-set` | :bomb: renamed `speed-limit-down` to `downloadLimit`
| `torrent-set` | :bomb: renamed `speed-limit-up-enabled` to `uploadLimited`
| `torrent-set` | :bomb: renamed `speed-limit-up` to `uploadLimit`
| `blocklist-update` | new method
| `port-test` | new method
| `session-get` | new arg `alt-speed-begin`
| `session-get` | new arg `alt-speed-down`
| `session-get` | new arg `alt-speed-enabled`
| `session-get` | new arg `alt-speed-end`
| `session-get` | new arg `alt-speed-time-enabled`
| `session-get` | new arg `alt-speed-up`
| `session-get` | new arg `blocklist-enabled`
| `session-get` | new arg `blocklist-size`
| `session-get` | new arg `peer-limit-per-torrent`
| `session-get` | new arg `seedRatioLimit`
| `session-get` | new arg `seedRatioLimited`
| `torrent-add` | new arg `files-unwanted`
| `torrent-add` | new arg `files-wanted`
| `torrent-add` | new arg `priority-high`
| `torrent-add` | new arg `priority-low`
| `torrent-add` | new arg `priority-normal`
| `torrent-get` | new arg `bandwidthPriority`
| `torrent-get` | new arg `fileStats`
| `torrent-get` | new arg `honorsSessionLimits`
| `torrent-get` | new arg `percentDone`
| `torrent-get` | new arg `pieces`
| `torrent-get` | new arg `seedRatioLimit`
| `torrent-get` | new arg `seedRatioMode`
| `torrent-get` | new arg `torrentFile`
| `torrent-get` | new ids option `recently-active`
| `torrent-reannounce` | new method
| `torrent-set` | new arg `bandwidthPriority`
| `torrent-set` | new arg `honorsSessionLimits`
| `torrent-set` | new arg `seedRatioLimit`
| `torrent-set` | new arg `seedRatioLimited`
Transmission 1.70 (`rpc-version-semver` 2.1.0, `rpc-version`: 6)
| Method | Description
|:---|:---
| `method torrent-set-location` | new method
Transmission 1.80 (`rpc-version-semver` 3.0.0, `rpc-version`: 7)
| Method | Description
|:---|:---
| `torrent-get` | :bomb: removed arg `announceResponse` (use `trackerStats instead`)
| `torrent-get` | :bomb: removed arg `announceURL` (use `trackerStats instead`)
| `torrent-get` | :bomb: removed arg `downloaders` (use `trackerStats instead`)
| `torrent-get` | :bomb: removed arg `lastAnnounceTime` (use `trackerStats instead`)
| `torrent-get` | :bomb: removed arg `lastScrapeTime` (use `trackerStats instead`)
| `torrent-get` | :bomb: removed arg `leechers` (use `trackerStats instead`)
| `torrent-get` | :bomb: removed arg `nextAnnounceTime` (use `trackerStats instead`)
| `torrent-get` | :bomb: removed arg `nextScrapeTime` (use `trackerStats instead`)
| `torrent-get` | :bomb: removed arg `scrapeResponse` (use `trackerStats instead`)
| `torrent-get` | :bomb: removed arg `scrapeURL` (use `trackerStats instead`)
| `torrent-get` | :bomb: removed arg `seeders` (use `trackerStats instead`)
| `torrent-get` | :bomb: removed arg `swarmSpeed`
| `torrent-get` | :bomb: removed arg `timesCompleted` (use `trackerStats instead`)
| `session-set` | new arg `incomplete-dir-enabled`
| `session-set` | new arg `incomplete-dir`
| `torrent-get` | new arg `magnetLink`
| `torrent-get` | new arg `metadataPercentComplete`
| `torrent-get` | new arg `trackerStats`
Transmission 1.90 (`rpc-version-semver` 3.1.0, `rpc-version`: 8)
| Method | Description
|:---|:---
| `session-set` | new arg `rename-partial-files`
| `session-get` | new arg `rename-partial-files`
| `session-get` | new arg `config-dir`
| `torrent-add` | new arg `bandwidthPriority`
| `torrent-get` | new trackerStats arg `lastAnnounceTimedOut`
Transmission 1.92 (`rpc-version-semver` 3.2.0, `rpc-version`: 8)
Note: `rpc-version` was not bumped in this release due to an oversight.
| Method | Description
|:---|:---
| `torrent-get` | new trackerStats arg `lastScrapeTimedOut`
Transmission 2.00 (`rpc-version-semver` 3.3.0, `rpc-version`: 9)
| Method | Description
|:---|:---
| `session-set` | new arg `start-added-torrents`
| `session-set` | new arg `trash-original-torrent-files`
| `session-get` | new arg `start-added-torrents`
| `session-get` | new arg `trash-original-torrent-files`
| `torrent-get` | new arg `isFinished`
Transmission 2.10 (`rpc-version-semver` 3.4.0, `rpc-version`: 10)
| Method | Description
|:---|:---
| `session-get` | new arg `cache-size-mb`
| `session-get` | new arg `units`
| `session-set` | new arg `idle-seeding-limit-enabled`
| `session-set` | new arg `idle-seeding-limit`
| `torrent-set` | new arg `seedIdleLimit`
| `torrent-set` | new arg `seedIdleMode`
| `torrent-set` | new arg `trackerAdd`
| `torrent-set` | new arg `trackerRemove`
| `torrent-set` | new arg `trackerReplace`
Transmission 2.12 (`rpc-version-semver` 3.5.0, `rpc-version`: 11)
| Method | Description
|:---|:---
| `session-get` | new arg `blocklist-url`
| `session-set` | new arg `blocklist-url`
Transmission 2.20 (`rpc-version-semver` 3.6.0, `rpc-version`: 12)
| Method | Description
|:---|:---
| `session-get` | new arg `download-dir-free-space`
| `session-close` | new method
Transmission 2.30 (`rpc-version-semver` 4.0.0, `rpc-version`: 13)
| Method | Description
|:---|:---
| `torrent-get` | :bomb: removed arg `peersKnown`
| `session-get` | new arg `isUTP` to the `peers` list
| `torrent-add` | new arg `cookies`
Transmission 2.40 (`rpc-version-semver` 5.0.0, `rpc-version`: 14)
| Method | Description
|:---|:---
| `torrent-get` | :bomb: values of `status` field changed
| `queue-move-bottom` | new method
| `queue-move-down` | new method
| `queue-move-top` | new method
| `session-set` | new arg `download-queue-enabled`
| `session-set` | new arg `download-queue-size`
| `session-set` | new arg `queue-stalled-enabled`
| `session-set` | new arg `queue-stalled-minutes`
| `session-set` | new arg `seed-queue-enabled`
| `session-set` | new arg `seed-queue-size`
| `torrent-get` | new arg `fromLpd` in peersFrom
| `torrent-get` | new arg `isStalled`
| `torrent-get` | new arg `queuePosition`
| `torrent-set` | new arg `queuePosition`
| `torrent-start-now` | new method
Transmission 2.80 (`rpc-version-semver` 5.1.0, `rpc-version`: 15)
| Method | Description
|:---|:---
| `torrent-get` | new arg `etaIdle`
| `torrent-rename-path` | new method
| `free-space` | new method
| `torrent-add` | new return arg `torrent-duplicate`
Transmission 3.00 (`rpc-version-semver` 5.2.0, `rpc-version`: 16)
| Method | Description
|:---|:---
| `session-get` | new request arg `fields`
| `session-get` | new arg `session-id`
| `torrent-get` | new arg `labels`
| `torrent-set` | new arg `labels`
| `torrent-get` | new arg `editDate`
| `torrent-get` | new request arg `format`
Transmission 4.0.0 (`rpc-version-semver` 5.3.0, `rpc-version`: 17)
| Method | Description
|:---|:---
| `/upload` | :warning: undocumented `/upload` endpoint removed
feat: add tr_torrentSetTrackerList(), tr_torrentGetTrackerList() (#2642) Add a getter/setter for torrent announce URLs as text that can be copied and pasted: one URL per line, with a blank line between tiers. C API: tr_torrentGetTrackerList() and tr_torrentSetTrackerList() RPC APi: `trackerList` in `torrent-get` and `torrent-set`. This deprecates `trackerAdd`, `trackerRemove`, and `trackerEdit` from the RPC API.
2022-02-18 17:52:01 +00:00
| `session-get` | **DEPRECATED** `download-dir-free-space`. Use `free-space` instead.
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
| `free-space` | new return arg `total-capacity`
refactor: do not mix torrent, default trackers
2022-02-20 19:00:52 +00:00
| `session-get` | new arg `default-trackers`
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
| `session-get` | new arg `rpc-version-semver`
| `session-get` | new arg `script-torrent-added-enabled`
| `session-get` | new arg `script-torrent-added-filename`
feat: run script when done seeding (#2621) * feat: add seeding-done script to core and rpc * feat: add seeding-done script to gtk client * feat: add seeding-done script to qt client * feat: add seeding-done script to transmission-remote * refactor: make Qt and GTK client text match * test: update tests Co-authored-by: Timothy Nibeaudeau <timothy.nibeaudeau@gmail.com>
2022-02-14 04:07:12 +00:00
| `session-get` | new arg `script-torrent-done-seeding-enabled`
| `session-get` | new arg `script-torrent-done-seeding-filename`
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
| `torrent-add` | new arg `labels`
feat: add rpc torrentGet.availability (#3252)
2022-06-11 17:06:07 +00:00
| `torrent-get` | new arg `availability`
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00
| `torrent-get` | new arg `file-count`
Limit bandwidth used by a group of torrents (#2761) * Add support for bandwidth groups. i.e. Bandwidth limit for a (user specified) group of torrents,
2022-03-18 13:11:59 +00:00
| `torrent-get` | new arg `group`
Add support for torrent-get calls with the key percentComplete (#2615) Co-authored-by: Michael Hadam <michael@hadam.us>
2022-02-13 07:27:47 +00:00
| `torrent-get` | new arg `percentComplete`
| `torrent-get` | new arg `primary-mime-type`
feat: use libpsl (#2575) Use libpsl to calculate public and private parts of URL hosts.
2022-02-12 17:30:27 +00:00
| `torrent-get` | new arg `tracker.sitename`
| `torrent-get` | new arg `trackerStats.sitename`
feat: add tr_torrentSetTrackerList(), tr_torrentGetTrackerList() (#2642) Add a getter/setter for torrent announce URLs as text that can be copied and pasted: one URL per line, with a blank line between tiers. C API: tr_torrentGetTrackerList() and tr_torrentSetTrackerList() RPC APi: `trackerList` in `torrent-get` and `torrent-set`. This deprecates `trackerAdd`, `trackerRemove`, and `trackerEdit` from the RPC API.
2022-02-18 17:52:01 +00:00
| `torrent-get` | new arg `trackerList`
Limit bandwidth used by a group of torrents (#2761) * Add support for bandwidth groups. i.e. Bandwidth limit for a (user specified) group of torrents,
2022-03-18 13:11:59 +00:00
| `torrent-set` | new arg `group`
feat: add tr_torrentSetTrackerList(), tr_torrentGetTrackerList() (#2642) Add a getter/setter for torrent announce URLs as text that can be copied and pasted: one URL per line, with a blank line between tiers. C API: tr_torrentGetTrackerList() and tr_torrentSetTrackerList() RPC APi: `trackerList` in `torrent-get` and `torrent-set`. This deprecates `trackerAdd`, `trackerRemove`, and `trackerEdit` from the RPC API.
2022-02-18 17:52:01 +00:00
| `torrent-set` | new arg `trackerList`
Limit bandwidth used by a group of torrents (#2761) * Add support for bandwidth groups. i.e. Bandwidth limit for a (user specified) group of torrents,
2022-03-18 13:11:59 +00:00
| `group-set` | new method
| `group-get` | new method
docs: move rpc-spec document from txt to markdown (#2606)
2022-02-11 16:48:21 +00:00