🇬🇧 English · 🇫🇷 Français

Applies to Hydranos 4.4.

For anyone connecting Sonarr, Radarr, Lidarr, autobrr, cross-seed or a script to Hydranos as if it were qBittorrent: what each call really does, what is constant or ignored, and the settings that work per application (Application recipes below). Moving an existing qBittorrent setup? Follow Migrating from qBittorrent first.

The qBittorrent shim is the set of routes under /api/v2/* on the same port as the web UI, port 8199 by default ([daemon] api_port). It imitates the qBittorrent WebUI API closely enough for the common automation tools:

• GET /api/v2/app/version answers v4.6.0 (plain text).
• GET /api/v2/app/webapiVersion answers 2.9.3.

Both are fixed on purpose: tools pick their calls from them. Adds follow the normal placement rule (category → engine and save path, see Categories and Routing). The shim lists every engine (extra engines included), each torrent once, but adds only into race or hoard (by category): it has no field to name an engine.

While Hydranos is still loading its torrents at startup, every /api/v2/* route, login included, answers 503 with a JSON body and Retry-After: 5; clients retry.

POST /api/v2/auth/login takes a form body (application/x-www-form-urlencoded) with username and password. Two kinds of credentials are accepted:

The answer is always HTTP 200: Ok. with a Set-Cookie: SID=… header, or Fails. (same answer for any wrong credential). A JSON body is not read: send a form.

The SID session expires after 1 hour without a request (each authenticated request renews it), at most 256 exist at once (the oldest is dropped), and all are lost when Hydranos restarts, so clients log in again. The cookie is Path=/; HttpOnly; SameSite=Lax, without Secure, so it works over plain HTTP. It also opens the whole native REST API: treat it like the API key.

Every other shim route requires authentication; a script can instead send the API key as an X-Api-Key header or an apikey query parameter. An unauthenticated shim call gets 403 Forbidden. (plain text) like real qBittorrent (the native REST API answers 401). POST /api/v2/auth/logout ends the session and needs no credentials.

Account, API key and exposure rules are on Security and Access.

# Log in (admin account, or any username + YOUR_API_KEY as password), keep the cookie
curl -i -c jar.txt \
  --data-urlencode 'username=admin' --data-urlencode 'password=YOUR_PASSWORD' \
  http://hydranos.example.org:8199/api/v2/auth/login

# Or skip the login and send the key
curl -H 'X-Api-Key: YOUR_API_KEY' http://hydranos.example.org:8199/api/v2/app/version

full = as qBittorrent; partial = works, differences listed; constant = fixed values; refused = answers 409 with the reason as plain text and changes nothing.

Notes:

• hashes is split on | or ,; all means every torrent of every engine. Write endpoints taking hashes accept a hash prefix (the first stored torrent that matches wins) and answer an empty 200 like qBittorrent, even when no hash matched: check with torrents/info, not the status code. Exceptions: the refused and 400 cases above, addTrackers/removeTrackers (hash, no all), createCategory (400 on an empty name, 409 on an existing one), torrents/add (Ok./Fails.). Calls taking a single hash (properties, files, filePrio, rename) need the full hash.
• Where parameters are read: the read calls (torrents/info, properties, files, trackers, export) and the calls added in 4.4 (setLocation, setShareLimits, setForceStart, the limit calls, filePrio, the toggles, rss/*) take them from the query string or a form body (cross-seed sends everything as a POST form). The older write calls (stop, start, delete, recheck, reannounce, tags, categories, trackers) read the form body only.
• Actions by hash reach every copy, extra engines included. To target one copy, use ?engine= on the REST API.

These routes are not registered. They answer HTTP 404 (a wrong verb on an existing route answers 405):

torrents/ setSuperSeeding, setAutoManagement, renameFile, renameFolder, editTracker, pieceStates, pieceHashes, webseeds; app/shutdown; transfer/ banPeers, toggleSpeedLimitsMode, speedLimitsMode; sync/torrentPeers; log/*, search/*.

The shim still reports WebAPI 2.9.3, so a tool may try them. For search, keep Prowlarr or autobrr.

torrents/info is the call Sonarr, Radarr, autobrr and cross-seed poll. It accepts, from the query string or a form body:

Every engine is listed, and each torrent once: the first engine holding it answers, in the order race, hoard, then the extra engines. A torrent held by both race and hoard is therefore reported as its race copy (race's save_path and content_path, and race as the fallback category). torrents/count and sync/maindata list the same rows.

Absent: infohash_v1, private, trackers_count, last_activity.

Since 4.4 uploaded and ratio are the real figures (4.3 kept them at 0). A seed goal set in Sonarr, Radarr, Lidarr or an autobrr rule now acts on them, and can remove torrents: see Application recipes.

Never returned: pausedUP/pausedDL, forcedUP/forcedDL, metaDL, missingFiles, checkingUP, checkingResumeData, moving, allocating (a torrent being moved keeps its state). A magnet still waiting for metadata is not listed at all. The paused/stopped filter matches stopped* rows only.

POST /api/v2/torrents/add is a multipart form:

Accepted but ignored in 4.4: the add fields rename and cookie (and any other unknown field) look like per-torrent options — Hydranos ignores them and logs qbit add: these fields have no effect in Hydranos — the torrent keeps the name from its .torrent; a .torrent URL needing a cookie must be fetched by the tool and sent as a file.

What decides the answer:

• Placement. A known category gives the engine (hoard mode → hoard, anything else → race) and its save path; an unknown category goes to race. With no folder from savepath or the category, the folder a client set with setPreferences save_path is used; if there is none either, the add is refused (log: no save path: category "X" is unknown and no savepath was given). The shim cannot name an engine.
• Already added (same torrent already in that engine) counts as success.
• Answer: Ok. (200) if at least one item was accepted; Fails. (HTTP 400) if every item was refused; Bad request (400) if there was neither a file nor a URL. Exception: an http(s) .torrent URL that downloads but whose add is then refused (for example no save path) still gets Ok.; check torrents/info or the log.
• Magnets: Ok. means resolution has started. The torrent enters the engine, and torrents/info, only when its metadata arrives; until then it sits in the Magnets card of the + Add Torrent tab (retried a few times, then kept there with the reason). The add options (caps, share limits, download order, layout, skip_checking) are kept with the request and applied once it resolves; a NoSubfolder magnet that turns out multi-file fails there with that reason.
• Data already on disk is hash-checked unless skip_checking is set. "On add" workflows run (for magnets, once resolved). The request body is limited to 2 MB.

Magnets, seed mode, .torrent URLs and dedup are explained on Adding Torrents and Existing Data.

H=http://hydranos.example.org:8199

# A .torrent file into the category "tv"
curl -b jar.txt -F '[email protected]' -F 'category=tv' $H/api/v2/torrents/add

# A magnet (use --form-string so curl does not interpret ; or @)
curl -b jar.txt \
  --form-string 'urls=magnet:?xt=urn:btih:0123456789abcdef0123456789abcdef01234567&tr=https://tracker.example.org/announce' \
  -F 'category=tv' $H/api/v2/torrents/add

# Seed mode on data already in place, explicit folder
curl -b jar.txt -F '[email protected]' -F 'savepath=/data/movies' -F 'skip_checking=true' $H/api/v2/torrents/add

# List a category, remove a torrent with its files
curl -b jar.txt "$H/api/v2/torrents/info?category=tv&filter=downloading"
curl -b jar.txt -d 'hashes=0123456789abcdef0123456789abcdef01234567&deleteFiles=true' $H/api/v2/torrents/delete

This is what Hydranos receives from autobrr when it sends a magnet:

sequenceDiagram
    participant AB as autobrr
    participant SH as Hydranos qBittorrent shim
    participant MR as Magnet resolver BEP 9
    participant EN as Engine race or hoard
    AB->>SH: POST auth/login (username, password)
    SH-->>AB: 200 Ok. and SID cookie
    AB->>SH: POST torrents/add (urls = magnet link, category)
    alt no savepath, no category save path, no preferences save_path
        SH-->>AB: 400 Fails.
    else placement found
        SH->>MR: store the magnet request and start resolving
        SH-->>AB: 200 Ok.
        MR->>MR: fetch metadata from peers and check it against the info hash
        MR->>EN: add the torrent at its save path (savepath, category or setPreferences), started unless added stopped
    end
    AB->>SH: POST torrents/reannounce (hashes)
    Note over SH,EN: a magnet still resolving has no copy yet, nothing is announced
    SH->>EN: announce now, every copy
    SH-->>AB: 200 (empty body)

Create your categories in Hydranos (tab Categories, + New: Name, Mode Race/Hoard, Save Path) before you point a tool at them, and use the same names in the tool. The shim's category calls cannot set a mode:

• createCategory always stores mode hoard. On a name that already exists it answers 409 Category already exists and leaves the category alone (mode, Graduate to and transit settings kept).
• A category created by a tool with an empty savePath is stored without a save path, and every later add into it is refused unless the tool sends savepath (or has set a default folder with setPreferences save_path).
• setCategory changes the label only; data and engine stay put. To move the data, use Change category + move files › in the web UI (see Categories and Routing).

Tags are labels with no effect on placement (Categories and Routing). deleteTags removes a tag from the list and from every torrent; removeCategories also clears that label from the torrents.

Each application uses its qBittorrent download-client type; unlisted settings stay at their defaults. Below, hydranos stands for the host, which depends on where Hydranos runs:

• same Docker network as the application: the service name, hydranos;
• behind a gluetun container (network_mode: "service:gluetun"): gluetun, because Hydranos has no network of its own and the name hydranos resolves to nothing (VPN and Egress);
• different networks, or not sure (for example Unraid's default bridge): the host machine's LAN address, e.g. 192.0.2.10, with port 8199 published.

Paths. The shim reports save_path and content_path as Hydranos sees them. Mount the same host folder at the same container path in both containers (Docker), or add a remote path mapping in the application (host = the host above, remote = Hydranos path, local = its own path).

Mode per category. If unsure, file your categories as Hoard. Race is for racing fresh uploads, and the race drain can delete race torrents with their data or move them (Race Drain and Graduation).

Settings › Download Clients › + › qBittorrent:

Seed ratio and seed time (indexer settings) now work both ways:

• they arrive with the add as ratioLimit / seedingTimeLimit and become the torrent's own share limits in Hydranos;
• Sonarr/Radarr read the real ratio and seeding_time, so their own seed-goal check can now be met (and remove the torrent if removal of completed downloads is enabled in the application; not tested by the maintainer).

Hydranos's own share limit, however, is held (log share limit reached, held) until the tracker's declared minimum seeding time is served, and forever for a tracker with no announce_min_seed_hours declared (a torrent with no tracker at all is not held); when it acts, it applies the engine's share_limit_action (stop by default), not a per-torrent action. See Queue, Share and Speed Limits. A workflow remains the other way to clean up after seeding.

If Test fails, check the host, port and credentials. Create the category in Hydranos first: Sonarr and Radarr usually call createCategory only for a category missing from torrents/categories, so an existing one is left alone, but one they create has no save path and every add into it is refused (not tested by the maintainer).

Settings › Clients › Add new: type qBittorrent, host http://hydranos:8199, username and password as above (or the API key as password). In a filter's action, choose this client and set:

autobrr sends magnets through urls (supported). Its client rules on speed, ratio or uploaded amount see the real values (transfer/info, torrents/info).

Point cross-seed at the shim with a URL that carries the credentials, then use injection:

// cross-seed config.js (v6 syntax; v5 uses qbittorrentUrl: "http://…" instead)
torrentClients: ["qbittorrent:http://admin:YOUR_PASSWORD@hydranos:8199"],
// or, with the API key: "qbittorrent:http://cross-seed:YOUR_API_KEY@hydranos:8199"
action: "inject",
skipRecheck: true,

• cross-seed injects with an explicit savepath and, for full matches, skip_checking=true: Hydranos adds the torrent in seed mode at that folder. Partial matches are sent for a recheck (not tested by the maintainer).
• The category cross-seed sends decides the engine. A category unknown to Hydranos still works because cross-seed sends a save path, but the torrent then lands in the race engine, where the drain can remove it. Create the categories cross-seed uses in Hydranos with mode hoard and a save path; with duplicateCategories it sends <category>.cross-seed, so create those too.
• Every engine is listed, so cross-seed also matches torrents held by extra engines (it injects into race or hoard, by category). A torrent held by race and hoard is seen once, as its race copy.
• cross-seed sends its calls as POST forms: torrents/files, properties, trackers, export and info read the hash from the body. torrents/files gives names under the torrent's folder and real piece ranges, so its matching sees the true layout.

No direct role: Prowlarr feeds indexers to Sonarr, Radarr and Lidarr. To grab from its search page, add Hydranos as a download client with the Sonarr settings above.

• Share limits (setShareLimits, ratioLimit/seedingTimeLimit at add, setPreferences max_ratio*): stored and shown, but they act only once the tracker's declared minimum seeding time (announce_min_seed_hours) is served, and never for a tracker without one (a torrent with no tracker at all is not held); the action is the engine's share_limit_action. Details: Queue, Share and Speed Limits.
• app/setPreferences needs a json field or a JSON body (400 without; a relative save_path is 400 before anything is written). Applied, to every local engine: max_ratio*, max_seeding_time*, max_inactive_seeding_time* (each value only with its *_enabled), max_ratio_act (2, super seeding, is logged and leaves the action unchanged), up_limit/dl_limit (live), max_active_downloads (live), max_active_uploads/max_active_torrents (only if queueing is already on), dont_count_slow_torrents and the slow_torrent_* keys, save_path, and dht, pex, lsd (written to the file, used at the next start). queueing itself cannot be switched through the shim.

Accepted but ignored in 4.4: other setPreferences keys (listen port, encryption, alternative speed limits…) look saved — they answer 200 and change nothing, logged as setPreferences: these keys have no effect in Hydranos — use the Config tab or default.toml.

Not implemented in 4.4: selective download — filePrio 0 (do not download) is refused with 409 and every file is always downloaded — priorities 1/6/7 only change the order. Also missing: a delta from sync/maindata (always a full update), per-tracker status and peer counts in torrents/trackers, seeds/total_wasted in properties, availability anywhere.

Other missing qBittorrent features: Migrating from qBittorrent.

Migrating from qBittorrent (step-by-step switch, Sonarr add sequence) · Categories and Routing · Adding Torrents and Existing Data · Security and Access · Trackers and Announces · Queue, Share and Speed Limits · RSS and Automatic Downloads · REST API