🇬🇧 English · 🇫🇷 Français

S'applique à Hydranos 4.4.

Pour vous qui branchez Sonarr, Radarr, Lidarr, autobrr, cross-seed ou un script sur Hydranos comme s'il s'agissait de qBittorrent : ce que fait réellement chaque appel, ce qui est constant ou ignoré, et les réglages qui fonctionnent pour chaque application (Recettes par application ci-dessous). Vous migrez une installation qBittorrent existante ? Suivez d'abord Migrer depuis qBittorrent.

Le shim qBittorrent est l'ensemble des routes sous /api/v2/*, sur le même port que l'interface web, port 8199 par défaut ([daemon] api_port). Il imite l'API WebUI de qBittorrent d'assez près pour les outils d'automatisation courants :

• GET /api/v2/app/version répond v4.6.0 (texte brut).
• GET /api/v2/app/webapiVersion répond 2.9.3.

Ces deux valeurs sont figées exprès : les outils choisissent leurs appels en fonction d'elles. Les ajouts suivent la règle de placement habituelle (catégorie → moteur et chemin de sauvegarde, voir Catégories & routage). Le shim liste tous les moteurs (moteurs supplémentaires compris), chaque torrent une seule fois, mais n'ajoute que dans race ou hoard (selon la catégorie) : il n'a aucun champ pour désigner un moteur.

Tant qu'Hydranos charge encore ses torrents au démarrage, toutes les routes /api/v2/*, login compris, répondent 503 avec un corps JSON et Retry-After: 5 ; les clients réessaient.

POST /api/v2/auth/login prend un corps de formulaire (application/x-www-form-urlencoded) avec username et password. Deux types d'identifiants sont acceptés :

La réponse est toujours HTTP 200 : Ok. avec un en-tête Set-Cookie: SID=…, ou Fails. (même réponse pour tout identifiant erroné). Un corps JSON n'est pas lu : envoyez un formulaire.

La session SID expire après 1 heure sans requête (chaque requête authentifiée la prolonge), 256 au plus existent en même temps (la plus ancienne est supprimée), et toutes sont perdues au redémarrage d'Hydranos : les clients se reconnectent alors. Le cookie est Path=/; HttpOnly; SameSite=Lax, sans Secure, il fonctionne donc en HTTP simple. Il ouvre aussi toute l'API REST native : traitez-le comme la clé API.

Toutes les autres routes du shim exigent une authentification ; un script peut à la place envoyer la clé API dans un en-tête X-Api-Key ou un paramètre de requête apikey. Un appel au shim non authentifié reçoit 403 Forbidden. (texte brut), comme le vrai qBittorrent (l'API REST native répond 401). POST /api/v2/auth/logout termine la session et ne demande aucun identifiant.

Les règles sur le compte, la clé API et l'exposition sont sur Sécurité & accès.

# 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 = comme qBittorrent ; partial = fonctionne, différences indiquées ; constant = valeurs figées ; refused = répond 409 avec la raison en texte brut et ne change rien.

Remarques :

• hashes est découpé sur | ou , ; all désigne tous les torrents de tous les moteurs. Les endpoints d'écriture qui prennent hashes acceptent un préfixe de hash (le premier torrent stocké qui correspond l'emporte) et répondent un 200 vide comme qBittorrent, même quand aucun hash n'a correspondu : vérifiez avec torrents/info, pas avec le code de statut. Exceptions : les cas refused et 400 ci-dessus, addTrackers/removeTrackers (hash, pas de all), createCategory (400 sur un nom vide, 409 sur un nom existant), torrents/add (Ok./Fails.). Les appels qui prennent un seul hash (properties, files, filePrio, rename) exigent le hash complet.
• Où sont lus les paramètres : les appels de lecture (torrents/info, properties, files, trackers, export) et les appels ajoutés en 4.4 (setLocation, setShareLimits, setForceStart, les appels de limite, filePrio, les bascules, rss/*) les prennent dans la query string ou un corps de formulaire (cross-seed envoie tout en formulaire POST). Les anciens appels d'écriture (arrêt, démarrage, suppression, revérification, réannonce, tags, catégories, trackers) ne lisent que le corps du formulaire.
• Les actions par hash atteignent chaque copie, moteurs supplémentaires compris. Pour cibler une seule copie, utilisez ?engine= sur l[[API REST|REST-API-FR]].

Ces routes ne sont pas enregistrées. Elles répondent HTTP 404 (un mauvais verbe sur une route existante répond 405) :

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

Le shim annonce tout de même WebAPI 2.9.3, un outil peut donc les essayer. Pour la recherche, gardez Prowlarr ou autobrr.

torrents/info est l'appel que Sonarr, Radarr, autobrr et cross-seed interrogent en boucle. Il accepte, dans la query string ou un corps de formulaire :

Tous les moteurs sont listés, et chaque torrent une seule fois : le premier moteur qui le détient répond, dans l'ordre race, hoard, puis les moteurs supplémentaires. Un torrent détenu à la fois par race et hoard est donc rapporté comme sa copie race (save_path et content_path de race, et race comme catégorie de repli). torrents/count et sync/maindata listent les mêmes lignes.

Absents : infohash_v1, private, trackers_count, last_activity.

Depuis la 4.4, uploaded et ratio sont les vrais chiffres (la 4.3 les laissait à 0). Un objectif de seed réglé dans Sonarr, Radarr, Lidarr ou une règle autobrr agit désormais sur eux, et peut supprimer des torrents : voir Recettes par application.

Jamais renvoyés : pausedUP/pausedDL, forcedUP/forcedDL, metaDL, missingFiles, checkingUP, checkingResumeData, moving, allocating (un torrent en cours de déplacement garde son état). Un magnet qui attend encore ses métadonnées n'est pas listé du tout. Le filtre paused/stopped ne correspond qu'aux lignes stopped*.

POST /api/v2/torrents/add est un formulaire multipart :

Accepté mais ignoré en 4.4 : les champs d'ajout rename et cookie (et tout autre champ inconnu) ressemblent à des options par torrent — Hydranos les ignore et journalise qbit add: these fields have no effect in Hydranos — le torrent garde le nom de son .torrent ; une URL .torrent qui exige un cookie doit être récupérée par l'outil et envoyée comme fichier.

Ce qui détermine la réponse :

• Placement. Une catégorie connue donne le moteur (mode hoard → hoard, tout le reste → race) et son chemin de sauvegarde ; une catégorie inconnue va dans race. Sans dossier venant de savepath ou de la catégorie, c'est le dossier qu'un client a défini avec setPreferences save_path qui sert ; s'il n'y en a pas non plus, l'ajout est refusé (journal : no save path: category "X" is unknown and no savepath was given). Le shim ne peut pas désigner un moteur.
• Déjà ajouté (même torrent déjà dans ce moteur) compte comme un succès.
• Réponse : Ok. (200) si au moins un élément a été accepté ; Fails. (HTTP 400) si tous les éléments ont été refusés ; Bad request (400) s'il n'y avait ni fichier ni URL. Exception : une URL .torrent http(s) qui se télécharge mais dont l'ajout est ensuite refusé (par exemple sans chemin de sauvegarde) reçoit quand même Ok. ; vérifiez torrents/info ou le journal.
• Magnets : Ok. signifie que la résolution a commencé. Le torrent n'entre dans le moteur, et dans torrents/info, qu'à l'arrivée de ses métadonnées ; d'ici là il reste dans la carte Magnets de l'onglet + Ajouter un torrent (+ Add Torrent) (quelques nouvelles tentatives, puis il y reste avec la raison). Les options d'ajout (plafonds, limites de partage, ordre de téléchargement, disposition, skip_checking) sont gardées avec la demande et appliquées une fois le magnet résolu ; un magnet NoSubfolder qui s'avère multi-fichiers échoue à ce moment-là avec cette raison.
• Les données déjà sur disque sont vérifiées par hash, sauf si skip_checking est défini. Les workflows « à l'ajout » s'exécutent (pour les magnets, une fois résolus). Le corps de la requête est limité à 2 Mo.

Magnets, mode seed, URL .torrent et dédup sont expliqués sur Ajouter des torrents & données existantes.

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

Voici ce que reçoit Hydranos quand autobrr envoie un magnet :

sequenceDiagram
    participant AB as autobrr
    participant SH as Shim qBittorrent Hydranos
    participant MR as Résolveur de magnets BEP 9
    participant EN as Moteur race ou hoard
    AB->>SH: POST auth/login (username, password)
    SH-->>AB: 200 Ok. et cookie SID
    AB->>SH: POST torrents/add (urls = lien magnet, category)
    alt pas de savepath, pas de chemin de sauvegarde de catégorie, pas de save_path de préférences
        SH-->>AB: 400 Fails.
    else placement trouvé
        SH->>MR: enregistre la demande de magnet et lance la résolution
        SH-->>AB: 200 Ok.
        MR->>MR: récupère les métadonnées auprès des pairs et les vérifie contre l'info hash
        MR->>EN: ajoute le torrent à son chemin de sauvegarde (savepath, catégorie ou setPreferences), démarré sauf ajout à l'arrêt
    end
    AB->>SH: POST torrents/reannounce (hashes)
    Note over SH,EN: un magnet encore en résolution n'a pas encore de copie, rien n'est annoncé
    SH->>EN: annonce immédiate, chaque copie
    SH-->>AB: 200 (corps vide)

Créez vos catégories dans Hydranos (onglet Catégories (Categories), + Nouveau (+ New) : Nom (Name), Mode Race/Hoard, Chemin d'enregistrement (Save Path)) avant d'y faire pointer un outil, et utilisez les mêmes noms dans l'outil. Les appels de catégorie du shim ne peuvent pas définir de mode :

• createCategory enregistre toujours le mode hoard. Sur un nom qui existe déjà, il répond 409 Category already exists et laisse la catégorie intacte (mode, Passer vers (Graduate to) et réglages de transit conservés).
• Une catégorie créée par un outil avec un savePath vide est enregistrée sans chemin de sauvegarde, et tout ajout ultérieur dans celle-ci est refusé, sauf si l'outil envoie savepath (ou a défini un dossier par défaut avec setPreferences save_path).
• setCategory ne change que l'étiquette ; les données et le moteur ne bougent pas. Pour déplacer les données, utilisez Changer de catégorie + déplacer les fichiers › (Change category + move files ›) dans l'interface web (voir Catégories & routage).

Les tags sont des étiquettes sans effet sur le placement (Catégories & routage). deleteTags retire un tag de la liste et de chaque torrent ; removeCategories retire aussi cette étiquette des torrents.

Chaque application utilise son type de client de téléchargement qBittorrent ; les réglages non mentionnés restent à leur valeur par défaut. Ci-dessous, hydranos désigne l'hôte, qui dépend de l'endroit où tourne Hydranos :

• même réseau Docker que l'application : le nom du service, hydranos ;
• derrière un conteneur gluetun (network_mode: "service:gluetun") : gluetun, car Hydranos n'a pas de réseau à lui et le nom hydranos ne se résout vers rien (VPN & sortie réseau) ;
• réseaux différents, ou en cas de doute (par exemple le bridge par défaut d'Unraid) : l'adresse LAN de la machine hôte, par exemple 192.0.2.10, avec le port 8199 publié.

Chemins. Le shim rapporte save_path et content_path tels qu'Hydranos les voit. Montez le même dossier de l'hôte au même chemin de conteneur dans les deux conteneurs (Docker), ou ajoutez un remote path mapping dans l'application (host = l'hôte ci-dessus, remote = chemin côté Hydranos, local = son propre chemin).

Mode par catégorie. En cas de doute, classez vos catégories en Hoard. Race sert à courir sur les nouveaux uploads, et le drain race peut supprimer des torrents race avec leurs données ou les déplacer (Drain race & graduation).

Settings › Download Clients › + › qBittorrent :

Ratio et durée de seed (réglages des indexeurs) fonctionnent désormais dans les deux sens :

• ils arrivent avec l'ajout sous forme de ratioLimit / seedingTimeLimit et deviennent les limites de partage propres au torrent dans Hydranos ;
• Sonarr/Radarr lisent les vrais ratio et seeding_time, leur propre contrôle d'objectif de seed peut donc maintenant être atteint (et supprimer le torrent si la suppression des téléchargements terminés est activée dans l'application ; non testé par le mainteneur).

La limite de partage propre à Hydranos est en revanche retenue (journal share limit reached, held) tant que la durée minimale de seed déclarée pour le tracker n'est pas accomplie, et indéfiniment pour un tracker sans announce_min_seed_hours déclaré (un torrent sans aucun tracker n'est pas retenu) ; quand elle agit, elle applique la share_limit_action du moteur (stop par défaut), pas une action par torrent. Voir File d'attente, limites de partage et de débit. Un workflow reste l'autre moyen de faire le ménage après le seed.

Si Test échoue, vérifiez l'hôte, le port et les identifiants. Créez d'abord la catégorie dans Hydranos : Sonarr et Radarr n'appellent en général createCategory que pour une catégorie absente de torrents/categories, une catégorie existante n'est donc pas touchée, mais celle qu'ils créent n'a pas de chemin de sauvegarde et tout ajout dans celle-ci est refusé (non testé par le mainteneur).

Settings › Clients › Add new : type qBittorrent, host http://hydranos:8199, nom d'utilisateur et mot de passe comme ci-dessus (ou la clé API comme mot de passe). Dans l'action d'un filtre, choisissez ce client et réglez :

autobrr envoie les magnets via urls (pris en charge). Ses règles client sur la vitesse, le ratio ou la quantité envoyée voient les vraies valeurs (transfer/info, torrents/info).

Faites pointer cross-seed vers le shim avec une URL qui porte les identifiants, puis utilisez l'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 injecte avec un savepath explicite et, pour les correspondances complètes, skip_checking=true : Hydranos ajoute le torrent en mode seed dans ce dossier. Les correspondances partielles sont envoyées pour une revérification (non testé par le mainteneur).
• C'est la catégorie envoyée par cross-seed qui décide du moteur. Une catégorie inconnue d'Hydranos fonctionne quand même parce que cross-seed envoie un chemin de sauvegarde, mais le torrent atterrit alors dans le moteur race, où le drain peut le supprimer. Créez dans Hydranos les catégories qu'utilise cross-seed, avec le mode hoard et un chemin de sauvegarde ; avec duplicateCategories, il envoie <category>.cross-seed, créez donc aussi celles-ci.
• Tous les moteurs sont listés, cross-seed fait donc aussi correspondre les torrents détenus par des moteurs supplémentaires (il injecte dans race ou hoard, selon la catégorie). Un torrent détenu par race et hoard est vu une seule fois, comme sa copie race.
• cross-seed envoie ses appels en formulaires POST : torrents/files, properties, trackers, export et info lisent le hash dans le corps. torrents/files donne les noms sous le dossier du torrent et les vraies plages de pièces, sa correspondance voit donc la vraie disposition.

Aucun rôle direct : Prowlarr fournit les indexeurs à Sonarr, Radarr et Lidarr. Pour récupérer depuis sa page de recherche, ajoutez Hydranos comme client de téléchargement avec les réglages Sonarr ci-dessus.

• Limites de partage (setShareLimits, ratioLimit/seedingTimeLimit à l'ajout, setPreferences max_ratio*) : enregistrées et affichées, mais elles n'agissent qu'une fois accomplie la durée minimale de seed déclarée pour le tracker (announce_min_seed_hours), et jamais pour un tracker qui n'en a pas (un torrent sans aucun tracker n'est pas retenu) ; l'action est la share_limit_action du moteur. Détails : File d'attente, limites de partage et de débit.
• app/setPreferences exige un champ json ou un corps JSON (400 sans ; un save_path relatif donne 400 avant toute écriture). Appliqués, à chaque moteur local : max_ratio*, max_seeding_time*, max_inactive_seeding_time* (chaque valeur seulement avec son *_enabled), max_ratio_act (2, super seeding, est journalisé et laisse l'action inchangée), up_limit/dl_limit (à chaud), max_active_downloads (à chaud), max_active_uploads/max_active_torrents (seulement si queueing est déjà activé), dont_count_slow_torrents et les clés slow_torrent_*, save_path, et dht, pex, lsd (écrits dans le fichier, utilisés au prochain démarrage). queueing lui-même ne peut pas être basculé via le shim.

Accepté mais ignoré en 4.4 : les autres clés de setPreferences (port d'écoute, chiffrement, limites de vitesse alternatives…) semblent enregistrées — elles répondent 200 et ne changent rien, journalisées sous setPreferences: these keys have no effect in Hydranos — utilisez l'onglet Config ou default.toml.

Non implémenté en 4.4 : le téléchargement sélectif — filePrio 0 (ne pas télécharger) est refusé avec 409 et chaque fichier est toujours téléchargé — les priorités 1/6/7 ne changent que l'ordre. Manquent aussi : un delta depuis sync/maindata (toujours une mise à jour complète), le statut et les nombres de pairs par tracker dans torrents/trackers, seeds/total_wasted dans properties, availability partout.

Autres fonctions de qBittorrent absentes : Migrer depuis qBittorrent.

Migrer depuis qBittorrent (bascule pas à pas, séquence d'ajout Sonarr) · Catégories & routage · Ajouter des torrents & données existantes · Sécurité & accès · Trackers & annonces · File d'attente, limites de partage et de débit · RSS et téléchargements automatiques · API REST