🇬🇧 English · 🇫🇷 Français

S'applique à Hydranos 4.4.

Pour scripter Hydranos : toutes les routes de l'API native (/api/*) en 4.4, celles qui fonctionnent, celles qui sont des bouchons, celles qui ont été retirées, des exemples curl. L'API compatible qBittorrent (/api/v2/*) est documentée sur Shim qBittorrent & automatisation, et l'endpoint MCP sur Serveur MCP.

Cette page est la carte. Les corps complets des requêtes et des réponses sont dans le fichier docs/API.md du dépôt ; les pages liées depuis chaque section expliquent ce que font les réglages.

Un seul port, 8199 par défaut ([daemon] api_port), sert l'interface web, /api, le shim qBittorrent et /mcp. Les exemples utilisent :

export HY=http://hydranos.example.org:8199
export KEY=YOUR_API_KEY

Les corps et les réponses sont en JSON, sauf mention contraire dans une ligne. Les réponses de plus de 32 octets sont compressées en gzip quand le client l'accepte (curl --compressed).

Il n'existe qu'un seul identifiant, la clé API ([daemon] api_key, 48 caractères hexadécimaux, générée au premier démarrage). Où la trouver, comment la renouveler et comment exposer Hydranos sans risque : Sécurité & accès.

POST /api/login (JSON {"username","password"}) ne pose pas de cookie : il renvoie {"api_key": "..."}, que l'interface web envoie ensuite en X-Api-Key. Un api_key vide dans la configuration refuse tous les appelants.

Formes de refus (testez le code de statut, pas le texte) :

Routes publiques (sans clé) : /health, /metrics, /, /static/*, /changelog.md, /install.sh, GET|POST /api/setup, POST /api/login, GET /api/startup, POST /api/v2/auth/login, POST /api/v2/auth/logout, POST /api/nodes/register (jeton d'enrôlement à la place de la clé), et POST /api/auth/api-key/confirm (la clé en attente d'une rotation à la place de la clé actuelle, voir Nœuds).

Le port s'ouvre avant que le catalogue soit chargé. Tant que le chargement n'est pas fini, seuls /, /static/*, /health ("status":"starting", 200), /metrics, GET /api/startup et GET /api/setup répondent. Tout autre chemin, /api/v2/* et /mcp compris, répond 503 avec Retry-After: 5 et {"error":"Hydranos is starting (<phase>): N of M torrents restored","startup":{…}} ; une autre méthode sur l'un des chemins ci-dessus (par exemple POST /api/setup) n'est pas routée et est refusée. Interrogez GET /api/startup jusqu'à "ready":true, ou réessayez après Retry-After. Les phases : Exploiter Hydranos.

Les erreurs sont du JSON {"error": "<message>"}, parfois avec d'autres champs :

• 400 : champ invalide ou manquant (les corps stricts nomment le champ inconnu).
• 404 : {"error":"torrent not found"}, ou moteur/nœud/job inexistant.
• 405 : le chemin existe, mais pas avec cette méthode (par exemple POST /api/race/settings depuis la 4.4).
• 409 : refusé à cause de l'état. Les déplacements de données ajoutent "reason" (hardlinks, space, shared, destination_taken, …) et un plan ; une sélection par filtre qui a grossi répond "reason":"grew" avec le nouveau count ; ajouter un torrent déjà présent répond 409.
• 410 : une route 3.x retirée en 4.4 ; le corps nomme la remplaçante (Routes retirées en 4.4).
• 503 + Retry-After: 5 : démarrage en cours (ci-dessus).

POST /api/torrents répond {"error","targets"} avec un statut qui dit pourquoi :

POST /api/torrents/upload répond aux mêmes refus par un 400, et par 409 pour déjà ajouté. Testez la classe du statut, et lisez error pour la raison.

• :info_hash est le hash v1 hexadécimal de 40 caractères. Certaines routes résolvent un préfixe plus court et agissent sur la première correspondance : envoyez toujours le hash complet.
• Les moteurs sont adressés par identifiant sous /api/engines/:id/... ; /api/race/... et /api/hoard/... sont des alias pour les deux moteurs qui existent toujours. Exception : GET /api/race/torrents liste tous les moteurs de rôle race.
• Le même torrent peut être dans plusieurs moteurs (une copie par moteur). Les routes de torrent choisissent une copie avec ?engine=<id>. L'ancienne graphie ?agent= (un nom de la 3.x) est aussi acceptée : local ou vide signifie la valeur par défaut, local-<id> signifie le moteur <id>.
• Les lignes de liste portent une étiquette dans le champ agent (nom historique) : local-<engine> pour une copie locale, <node>-<engine> pour une ligne fusionnée depuis un nœud déclaré. Les routes par torrent répondent 404 pour une ligne de nœud ; /api/selection/* relaie l'action au nœud qui la détient.

Statut (champs : Supervision) :

curl -s -H "X-Api-Key: $KEY" "$HY/api/status"

Les 100 premiers torrents hoard de la catégorie tv, les plus récents d'abord (filtre et pagination côté serveur) :

curl -s --compressed -H "X-Api-Key: $KEY" \
  "$HY/api/hoard/page?category=tv&limit=100&sort=added_time"

Créer une catégorie (il n'y a pas de chemin de sauvegarde par défaut, les ajouts en ont donc besoin d'un) :

curl -s -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"name":"tv","save_path":"/data/tv","mode":"hoard"}' "$HY/api/categories"

Ajouter un fichier .torrent avec une catégorie (multipart) :

curl -s -H "X-Api-Key: $KEY" \
  -F "[email protected]" -F "category=tv" "$HY/api/torrents/upload"

Ajoutez -F "seed_mode=true" pour seeder des données déjà sur disque sans les hacher (mode seed ; risques : Ajouter des torrents & données existantes).

Arrêter tous les torrents hoard de la catégorie old (une action groupée par filtre ; comptez d'abord, envoyez le compte comme expect) :

N=$(curl -s -H "X-Api-Key: $KEY" "$HY/api/hoard/page?category=old&limit=1" | jq .filtered)
curl -s -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d "{\"selection\":{\"filter\":\"category=old\",\"view\":\"hoard\",\"expect\":$N},\"params\":{}}" \
  "$HY/api/selection/stop"
# 202 {"job":"...","total":N}  ->  poll GET /api/selection/jobs/<job>

Statut : ✓ fonctionne · ◐ fonctionne avec une réserve. Les routes bouchons n'apparaissent que dans Bouchons et routes retirées en 4.4.

Comment un ajout choisit son moteur et son chemin de sauvegarde : Catégories & routage. Sans engine ni mode, c'est la catégorie qui décide. create_subfolder donne à un torrent à fichier unique un dossier à lui, au nom du torrent ; il n'est pas appliqué aux magnets sur cette route.

Chaque ligne /api/engines/:id/... répond aussi en /api/hoard/... et /api/race/..., sauf pinned, pause-all et resume-all (alias hoard uniquement) et rate-limits, share-limits (sans alias : utilisez /api/engines/race/… ou /api/engines/hoard/…).

Ce que font la file d'attente, les limites de partage et les limites de débit : File d'attente, limites de partage et de débit.

Paramètres de pagination de .../page : offset (par défaut 0), limit (par défaut 500, borné entre 1 et 5000), sort (un champ de ligne, par défaut added_time), order=asc (décroissant par défaut), facets=1 (ajoute les comptes par catégorie/tag/tracker), fields=hash (hashes seulement). Filtres : search (mots combinés en ET, ou un préfixe de hash hexadécimal de 6 caractères ou plus), category, tag, tracker, error_class et leurs variantes _not (listes séparées par des virgules, __none__ = sans valeur), state (un état de ligne comme seeding, ou __active__, __error__, __tracker_err__, __pinned__). La réponse est {"total","filtered","offset","limit","rows","facets"}. Une page fusionne aussi les autres moteurs locaux du même rôle et les lignes des nœuds déclarés. Depuis la 4.4, les mêmes filtres s'appliquent aussi aux routes de liste complète GET /api/{hoard,race}/torrents et /api/engines/:id/torrents ; sans filtre, elles renvoient le moteur entier (/api/race/torrents : tous les moteurs de rôle race) et ignorent offset/limit. Avec un filtre, n'envoyez pas offset/limit : un limit inférieur à 5000 réduit la réponse à une seule page.

Bug connu en 4.4. Sur une route de liste complète, un filtre plus un offset (avec limit absent ou à 5000 et plus) boucle sans fin dès que 5000 lignes correspondent à partir de cet offset : la route pagine en interne en ajoutant son propre offset, celui de l'appelant vient en premier et l'emporte, donc la fenêtre n'avance jamais.

POST /api/selection/:action exécute une action sur de nombreux torrents sous forme de tâche groupée en mémoire (le menu contextuel de l'interface web l'utilise). Elle répond 202 {"job","total"} ; interrogez GET /api/selection/jobs/:id (conservé 1 h après la fin, perdu au redémarrage). POST /api/selection/jobs/:id/cancel arrête entre deux torrents. Ces tâches ne sont pas les jobs persistants de l'onglet Jobs : voir Jobs, actions groupées & déplacement.

Corps : {"selection": ..., "params": {...}}, strict (clés inconnues → 400).

• Par lignes : "selection":{"items":[{"hash":"<40 hex>","agent":"local-hoard"}]}. Chaque ligne agit sur sa propre copie (le moteur de son étiquette agent).
• Par filtre : "selection":{"filter":"category=tv&state=seeding","view":"hoard","expect":<count>}, "exclude":[items] facultatif. filter ne prend que les clés de filtre listées sous Listes et moteurs ; view est un identifiant de moteur (par défaut hoard) ; expect est obligatoire.

Signification de chaque réglage : Trackers & annonces.

Corps : Workflows, Jobs, actions groupées & déplacement.

Voir Drain race & graduation.

Les anciennes routes 3.x /api/agents* ont été retirées en 4.4 : tout chemin et toute méthode sous /api/agents répondent 410 Gone avec "see":["/api/engines","/api/nodes"]. Utilisez /api/engines pour les moteurs de cette machine et /api/nodes pour les autres machines (Mettre à jour depuis la 3.x).

Assistant d'import : Migrer depuis qBittorrent. Magnets, dossiers surveillés, dédup : Ajouter des torrents & données existantes.

Nouveau en 4.4. Flux, dossiers et règles de téléchargement ; une règle est le document de règle de qBittorrent (rss/setRule). Les routes /api/v2/rss/* des clients qBittorrent atteignent les mêmes flux et les mêmes règles.

Règles, filtres et sort d'un article : RSS et téléchargements automatiques.

Corps : docs/API.md. Les modes et l'onglet Réseau : Réseau : ports & redirection ; kill switch et sortie du démon : VPN & sortie réseau ; tunnels : WireGuard géré.

Mot de passe oublié : hydranos reset-password sur l'hôte (Sécurité & accès).

Champs de /api/status, /api/benchmark/current, .../trackers/current et /api/health/anomalies : docs/API.md › Monitoring. /api/status ne couvre que race et hoard (moteurs supplémentaires : stats de /api/engines) ; dans /api/benchmark/current, *_announce_rate, *_announce_fail_rate, race_avg_share et hoard_session_uploaded valent toujours 0.

Ce que rapporte chaque route de supervision : Supervision & journaux.

Ces routes répondent mais ne font pas ce que leur nom indique :

Routes retirées en 4.4. C'étaient des bouchons jusqu'à la 4.3 (une réponse en forme de succès qui ne faisait rien) et aucun écran ne les appelait. Un chemin retiré répond 404 ; une méthode retirée sur un chemin qui garde son GET répond 405 ; les routes 3.x répondent 410 avec un corps qui nomme la remplaçante.

Les autres routes listées comme bouchons ou constantes sur la page 4.3 fonctionnent en 4.4 (lignes ci-dessus).