class

QBittorrent::Api::Torrents

Inherits Reference < Object

Reopens Api::Torrents (see torrents.cr for the class definition and the read/info endpoints) to add the lifecycle & queue mutation endpoints of the torrents group (ext/api-map.md §2.5):

  • adding torrents (torrents/add) from magnet/HTTP URLs and/or a raw .torrent upload;
  • the lifecycle actions start/stop/delete/recheck/reannounce;
  • the queue-priority actions topPrio/bottomPrio/increasePrio/ decreasePrio.

All of these are POST actions that return an empty 200 on success (torrents/add returns the text Ok./Fails.), so every method here returns Nil. The *hashes* helpers accept "all", a single hash, or an enumerable of hashes (joined with |`).

Constructors

new(client : Client)
Source

Instance methods

add(urls : String | Enumerable(String) | Nil = nil, torrent : String | Bytes | Nil = nil, torrent_filename : String = "torrent", savepath : String | Nil = nil, category : String | Nil = nil, tags : String | Enumerable(String) | Nil = nil, stopped : Bool | Nil = nil, stop_condition : String | Nil = nil, content_layout : String | Nil = nil, add_to_top_of_queue : Bool | Nil = nil, download_path : String | Nil = nil, use_download_path : Bool | Nil = nil, rename : String | Nil = nil, up_limit : Int64 | Nil = nil, dl_limit : Int64 | Nil = nil, ratio_limit : Float64 | Nil = nil, seeding_time_limit : Int32 | Nil = nil, auto_tmm : Bool | Nil = nil, sequential_download : Bool | Nil = nil, first_last_piece_prio : Bool | Nil = nil, cookie : String | Nil = nil) : Nil

POST torrents/add — add one or more torrents from urls (magnet or HTTP links) and/or a single raw .torrent upload (torrent content, announced as torrent_filename). At least one source must be given.

urls may be a single string or an enumerable of links (joined with newlines, as the API expects). Supplying torrent sends the request as multipart/form-data (the transport torrents/add requires for file uploads); with only urls the multipart body carries just the fields.

The remaining parameters map to the qB 5.x add options: savepath, category, tags (a single string or an enumerable joined with commas), stopped (add without starting), stop_condition (None/MetadataReceived/FilesChecked), content_layout (Original/Subfolder/NoSubfolder), add_to_top_of_queue, download_path / use_download_path (incomplete-files path), rename (initial torrent name), up_limit / dl_limit (bytes/s), ratio_limit, seeding_time_limit (minutes), auto_tmm, sequential_download, first_last_piece_prio and cookie (sent when downloading from urls).

Raises ArgumentError when neither urls nor torrent is given, and a QBittorrent::Error when the server rejects every source (Fails.).

Source
add_peers(hashes : String | Enumerable(String), peers : String | Enumerable(String)) : Nil

POST torrents/addPeers — add peers to the torrents. peers is a single host:port entry or an enumerable (joined with |).

Source
add_tags(hashes : String | Enumerable(String), tags : String | Enumerable(String)) : Nil

POST torrents/addTags — add tags to the torrents. tags is a single tag or an enumerable (joined with commas).

Source
add_trackers(hash : String, urls : String | Enumerable(String)) : Nil

POST torrents/addTrackers — add tracker urls to the torrent hash. urls is a single URL or an enumerable (joined with newlines).

Source
bottom_priority(hashes : String | Enumerable(String)) : Nil

POST torrents/bottomPrio — move the given torrents to the bottom of the queue. Requires queueing enabled (409 otherwise).

Source
categories

GET torrents/categories — all categories, keyed by category name.

Source
create_category(category : String, save_path : String | Nil = nil) : Nil

POST torrents/createCategory — create category, optionally with a save_path.

Source
create_tags(tags : String | Enumerable(String)) : Nil

POST torrents/createTags — create tags. tags is a single tag or an enumerable (joined with commas).

Source
decrease_priority(hashes : String | Enumerable(String)) : Nil

POST torrents/decreasePrio — move the given torrents one step down the queue. Requires queueing enabled (409 otherwise).

Source
delete(hashes : String | Enumerable(String), delete_files : Bool) : Nil

POST torrents/delete — remove the given torrents. When delete_files is true the downloaded data is deleted from disk as well.

Source
delete_tags(tags : String | Enumerable(String)) : Nil

POST torrents/deleteTags — delete tags. tags is a single tag or an enumerable (joined with commas).

Source
download_limit(hashes : String | Enumerable(String)) : Hash(String, Int64)

torrents/downloadLimit — per-torrent download limits as {hash => bytes/s} (0 = unlimited). Sent as a POST form (the transport most reliably accepted across 5.x builds; see api-map §7.6).

Source
edit_category(category : String, save_path : String) : Nil

POST torrents/editCategory — set category's save path to save_path.

Source
edit_tracker(hash : String, orig_url : String, new_url : String) : Nil

POST torrents/editTracker — replace tracker orig_url with new_url on the torrent hash.

Source
export(hash : String) : Bytes

GET torrents/export — export the torrent hash as raw .torrent file bytes (qB 5.x runtime; thinly documented on the wiki).

Source
files(hash : String, indexes : String | Enumerable(Int32) | Enumerable(String) | Nil = nil) : Array(Model::TorrentFile)

GET torrents/files — files of the torrent hash. indexes restricts to specific file indexes (a single index/string or an enumerable, joined with |).

Source
increase_priority(hashes : String | Enumerable(String)) : Nil

POST torrents/increasePrio — move the given torrents one step up the queue. Requires queueing enabled (409 otherwise).

Source
info(filter : Model::TorrentFilter | Nil = nil, category : String | Nil = nil, tag : String | Nil = nil, sort : String | Nil = nil, reverse : Bool | Nil = nil, limit : Int32 | Nil = nil, offset : Int32 | Nil = nil, hashes : String | Enumerable(String) | Nil = nil) : Array(Model::TorrentInfo)

GET torrents/info — list torrents, optionally filtered/sorted/paged.

filter narrows by state group (mapped to its API string via the enum); category and tag narrow by category/tag name (pass "" to match the uncategorised/untagged set). sort names a TorrentInfo field to sort by and reverse reverses that order. limit/offset page the result. hashes restricts to specific torrents; pass a single hash string or an enumerable of hashes (joined with |).

Source
piece_hashes(hash : String) : Array(String)

GET torrents/pieceHashes — per-piece hashes of the torrent hash, in piece order (hex strings).

Source
piece_states(hash : String) : Array(Model::PieceState)

GET torrents/pieceStates — per-piece download state of the torrent hash, in piece order.

The wire form is an array of ints (0/1/2); they are decoded here through PieceState's strict enum codec (the value set is closed).

Source
properties(hash : String) : Model::TorrentProperties

GET torrents/properties — detailed properties of the torrent hash.

Source
reannounce(hashes : String | Enumerable(String)) : Nil

POST torrents/reannounce — re-announce the given torrents to their trackers.

Source
recheck(hashes : String | Enumerable(String)) : Nil

POST torrents/recheck — force a re-check of the given torrents.

Source
remove_categories(categories : String | Enumerable(String)) : Nil

POST torrents/removeCategories — delete one or more categories. categories is a single name or an enumerable (joined with newlines).

Source
remove_tags(hashes : String | Enumerable(String), tags : String | Enumerable(String)) : Nil

POST torrents/removeTags — remove tags from the torrents (an empty tags removes all). tags is a single tag or an enumerable (joined with commas).

Source
remove_trackers(hash : String, urls : String | Enumerable(String)) : Nil

POST torrents/removeTrackers — remove tracker urls from the torrent hash. urls is a single URL or an enumerable (joined with |).

Source
rename(hash : String, name : String) : Nil

POST torrents/rename — rename the torrent hash to name.

Source
rename_file(hash : String, old_path : String, new_path : String) : Nil

POST torrents/renameFile — rename a file within the torrent hash from old_path to new_path (both relative to the torrent root).

Source
rename_folder(hash : String, old_path : String, new_path : String) : Nil

POST torrents/renameFolder — rename a folder within the torrent hash from old_path to new_path (both relative to the torrent root).

Source
set_auto_management(hashes : String | Enumerable(String), enable : Bool) : Nil

POST torrents/setAutoManagement — enable/disable automatic torrent management (auto-TMM) for the torrents.

Source
set_category(hashes : String | Enumerable(String), category : String) : Nil

POST torrents/setCategory — assign category (pass "" to clear).

Source
set_download_limit(hashes : String | Enumerable(String), limit : Int64) : Nil

POST torrents/setDownloadLimit — per-torrent download rate limit, limit in bytes/s (0 = unlimited).

Source
set_download_path(id : String | Enumerable(String), path : String) : Nil

POST torrents/setDownloadPath — set the incomplete-files download path (qB 5.x). id is a hash argument (the API names the field id).

Source
set_force_start(hashes : String | Enumerable(String), value : Bool) : Nil

POST torrents/setForceStart — set force-start on the torrents.

Source
set_location(hashes : String | Enumerable(String), location : String) : Nil

POST torrents/setLocation — move the torrents' content to location.

Source
set_save_path(id : String | Enumerable(String), path : String) : Nil

POST torrents/setSavePath — set the (completed) save path (qB 5.x). id is a hash argument (the API names the field id).

Source
set_share_limits(hashes : String | Enumerable(String), ratio_limit : Float64, seeding_time_limit : Int32, inactive_seeding_time_limit : Int32) : Nil

POST torrents/setShareLimits — per-torrent seeding limits.

ratio_limit is the share ratio (-2 = use the global limit, -1 = unlimited). seeding_time_limit and inactive_seeding_time_limit are in minutes (-2 = global, -1 = unlimited); the inactive limit is a qB 5.x addition.

Source
set_super_seeding(hashes : String | Enumerable(String), value : Bool) : Nil

POST torrents/setSuperSeeding — set super-seeding on the torrents.

Source
set_upload_limit(hashes : String | Enumerable(String), limit : Int64) : Nil

POST torrents/setUploadLimit — per-torrent upload rate limit, limit in bytes/s (0 = unlimited).

Source
start(hashes : String | Enumerable(String)) : Nil

POST torrents/start — start (resume) the given torrents. qB 5.x rename of torrents/resume. hashes is "all", a single hash, or an enumerable.

Source
stop(hashes : String | Enumerable(String)) : Nil

POST torrents/stop — stop (pause) the given torrents. qB 5.x rename of torrents/pause.

Source
tags

GET torrents/tags — all tag names (qB 5.x).

Source
toggle_first_last_piece_priority(hashes : String | Enumerable(String)) : Nil

POST torrents/toggleFirstLastPiecePrio — flip first/last-piece priority on/off for the torrents.

Source
toggle_sequential_download(hashes : String | Enumerable(String)) : Nil

POST torrents/toggleSequentialDownload — flip sequential download on/off for the torrents.

Source
top_priority(hashes : String | Enumerable(String)) : Nil

POST torrents/topPrio — move the given torrents to the top of the queue. Requires queueing to be enabled (the server answers 409 otherwise).

Source
trackers(hash : String) : Array(Model::Tracker)

GET torrents/trackers — trackers of the torrent hash (includes the synthetic DHT/PeX/LSD pseudo-rows).

Source
upload_limit(hashes : String | Enumerable(String)) : Hash(String, Int64)

torrents/uploadLimit — per-torrent upload limits as {hash => bytes/s} (0 = unlimited). Sent as a POST form (see api-map §7.6).

Source
webseeds(hash : String) : Array(Model::WebSeed)

GET torrents/webseeds — web seeds of the torrent hash.

Source