L'API HolyArrs

Appelez depuis vos propres scripts la même API JSON que celle de l’interface web, sous /api/v1.

Faire votre premier appel

1. Ouvrez Settings > API > API keys (Paramètres > API > clés API) et créez une clé avec seulement les portées dont elle a besoin. Copiez-la tout de suite, car elle n’est affichée qu’une fois.
2. Envoyez-la dans l’en-tête X-Api-Key à chaque appel. Ne la mettez jamais dans l’adresse.
3. Appelez l’adresse de base http://your-server:6262/api/v1. Avec une base d’URL /holyarrs, appelez http://your-server:6262/holyarrs/api/v1.

export HOLYARRS_KEY=...your key...
curl -H "X-Api-Key: $HOLYARRS_KEY" "http://your-server:6262/api/v1/health"

Vous devriez recevoir du JSON en réponse. Les erreurs ont la forme {"error": "plain words"} avec un code HTTP. Les secrets reviennent masqués.

Options

Choisir une portée

Portée	Autorise
health_read	Seulement le flux de santé, pour les outils de supervision
read	Les routes de lecture, flux de santé compris
write	Les modifications, sauf les routes d’administration et les commandes
admin	Personnes, invitations, limites de demandes, clés API, mots de passe et double authentification, paramètres de connexion, restauration
control	Interrupteurs des modules, phases, applications liées, redémarrage et arrêt
all	read, write et admin. Pas control

Donnez health_read à un outil de supervision, et rien d’autre.

Trouver une route

Settings > API affiche l’adresse de base, les portées, des exemples d’appels et toutes les routes avec leur portée et leur permission. Le fichier OpenAPI se trouve à /api/v1/openapi.json quand vous êtes connecté. Routes de l’API liste toutes les routes.

Parler à HolyArrs comme à une ancienne application

Seerr, Overseerr, Bazarr et les applications du même genre n’utilisent pas cette API. Elles parlent à HolyArrs comme s’il s’agissait de Sonarr et de Radarr, avec leurs propres clés. Voir API des anciennes applications.

Si ça ne fonctionne pas

Symptôme. 401 à chaque appel. Cause. La clé est fausse ou supprimée. Solution. Créez une nouvelle clé.

Symptôme. 403 sur une route. Cause. La portée de la clé ne couvre pas cette route. Solution. Vérifiez la portée de la route dans Settings > API.

Symptôme. 404 à chaque appel. Cause. La base d’URL manque. Solution. Mettez-la avant /api/v1. Voir Base d’URL.

Pour les experts

Ajouter une route

Les routes se trouvent dans le fichier routes.go de chaque module. Chacune est enregistrée avec sa méthode, son chemin et sa permission. Chaque route a donc un contrôle de permission.

openapi.json est produit à partir des routes. TestOpenAPIGenerated échoue dès qu’ils divergent, alors mettez-le à jour dans le même changement. Un instantané de la table des routes échoue aussi quand une route est ajoutée, supprimée ou déplacée sans mise à jour de l’instantané.

Une fois publiés, les chemins et les noms de champs restent. Ajoutez des champs, ne les renommez jamais. Après un changement, lancez go run ./app/backend/tools/apidoc pour réécrire Routes de l’API.

Appels au serveur de métadonnées

HolyArrs récupère les noms, les images et les identifiants auprès du serveur de métadonnées HolyArrs. Pour faire pointer une installation vers un autre serveur, utilisez HOLYARRS_METADATA_URL. Le code du serveur n’est pas dans ce dépôt.

Enregistrement. À sa première recherche, une installation appelle POST /v1/installations sans corps. La réponse est 201 avec {"schema_version":1,"token":"hai_..."}. L’application stocke le jeton chiffré et envoie Authorization: Bearer <token> à chaque recherche. Elle s’enregistre une seule fois. Après un 401, elle ne s’enregistre pas de nouveau : une installation révoquée reste donc révoquée. Au-delà de la limite horaire par groupe d’adresses, la réponse est 429 registration_limit avec Retry-After.

Recherche (toutes en GET)	Route
Recherche	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
Film	/v1/movies/tmdb/{id}
Série	/v1/shows/{tmdb or tvmaze}/{id}
Saison	/v1/shows/tmdb/{id}/seasons/{n} (la saison 0 contient les épisodes spéciaux)
Musique	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

Les paramètres inconnus ou répétés sont refusés. Les identifiants d’un fournisseur ne sont jamais utilisés pour un autre.

Une bonne réponse contient schema_version, source, source_id, fetched_at, expires_at, completeness, stale et data. Traitez le HTML des résumés comme du texte brut.

Code	Signification
400	Requête invalide, ne réessayez pas
401	Jeton invalide ou révoqué, ne réessayez pas
404	Aucun enregistrement de ce type
429	Trop d’appels, attendez le délai Retry-After
503	Occupé, attendez et réessayez une fois

Voir aussi

• Routes de l’API
• API des anciennes applications
• Variables d’environnement