Die HolyArrs-API

Einrichtung

Rufe aus deinen eigenen Skripten dieselbe JSON-API auf, die auch die Web-App nutzt. Sie liegt unter /api/v1.

Dein erster Aufruf

Öffne Settings > API > API keys (Einstellungen > API > API-Schlüssel) und erstelle einen Schlüssel, der nur die nötigen Scopes hat. Kopiere ihn sofort, denn er wird nur einmal angezeigt.
Sende ihn bei jedem Aufruf im Header X-Api-Key. Schreibe ihn nie in die Adresse.
Rufe die Basisadresse http://your-server:6262/api/v1 auf. Mit einer URL base von /holyarrs rufst du http://your-server:6262/holyarrs/api/v1 auf.

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

Du solltest JSON zurückbekommen. Fehler kommen als {"error": "plain words"} mit einem HTTP-Status. Geheime Werte kommen maskiert zurück.

Optionen

Einen Scope wählen

Scope	Erlaubt
`health_read`	Nur den Zustands-Feed, für Monitoring-Tools
`read`	Die lesenden Routen, einschließlich Zustands-Feed
`write`	Änderungen, außer Admin-Routen und Steuerung
`admin`	Personen, Einladungen, Anfragelimits, API-Schlüssel, Passwörter und Zwei-Faktor, Anmeldeeinstellungen, Wiederherstellung
`control`	Bereichsschalter, Stufen, verknüpfte Apps, Neustart und Herunterfahren
`all`	`read`, `write` und `admin`. Nicht `control`

Gib einem Monitoring-Tool health_read und sonst nichts.

Eine Route finden

Settings > API zeigt die Basisadresse, die Scopes, Beispielaufrufe und jede Route mit ihrem Scope und ihrer Berechtigung. Die OpenAPI-Datei liegt unter /api/v1/openapi.json, wenn du angemeldet bist. API-Routen listet jede Route auf.

Mit HolyArrs wie mit einer bisherigen App sprechen

Seerr, Overseerr, Bazarr und ähnliche Apps nutzen diese API nicht. Sie sprechen mit HolyArrs, als wäre es Sonarr und Radarr, und haben dafür eigene Schlüssel. Siehe API der bisherigen Apps.

Wenn es nicht funktioniert

Symptom. 401 bei jedem Aufruf. Ursache. Der Schlüssel ist falsch oder gelöscht. Lösung. Erstelle einen neuen Schlüssel.

Symptom. 403 bei einer Route. Ursache. Der Scope des Schlüssels deckt diese Route nicht ab. Lösung. Prüfe den Scope der Route unter Settings > API.

Symptom. 404 bei jedem Aufruf. Ursache. Die URL base fehlt. Lösung. Setze sie vor /api/v1. Siehe URL base.

Für Fortgeschrittene

Eine Route hinzufügen

Die Routen stehen in der routes.go des jeweiligen Moduls. Jede wird mit Methode, Pfad und Berechtigung registriert. So hat jede Route eine Berechtigungsprüfung.

openapi.json entsteht aus den Routen. TestOpenAPIGenerated schlägt fehl, wenn beide auseinanderlaufen, also aktualisiere die Datei in derselben Änderung. Auch ein Snapshot der Routentabelle schlägt fehl, wenn eine Route hinzukommt, entfällt oder verschoben wird, ohne dass der Snapshot aktualisiert wurde.

Nach der Veröffentlichung bleiben Pfade und Feldnamen bestehen. Füge Felder hinzu, benenne sie nie um. Führe nach einer Änderung go run ./app/backend/tools/apidoc aus, um API-Routen neu zu schreiben.

Aufrufe an den Metadaten-Server

HolyArrs holt Namen, Bilder und IDs vom HolyArrs-Metadaten-Server. Mit HOLYARRS_METADATA_URL richtest du eine Installation auf einen anderen Server aus. Der Code des Servers liegt nicht in diesem Repo.

Registrierung. Bei ihrer ersten Abfrage ruft eine Installation POST /v1/installations ohne Body auf. Die Antwort ist 201 mit {"schema_version":1,"token":"hai_..."}. Die App speichert das Token verschlüsselt und sendet bei jeder Abfrage Authorization: Bearer <token>. Sie registriert sich einmal. Nach einem 401 registriert sie sich nicht erneut, eine widerrufene Installation bleibt also widerrufen. Über dem Stundenlimit pro Adressgruppe lautet die Antwort 429 registration_limit mit Retry-After.

Abfrage (immer GET)	Route
Suche	`/v1/search?provider=tmdb&kind=movie&q=Example&page=1`
Film	`/v1/movies/tmdb/{id}`
Serie	`/v1/shows/{tmdb or tvmaze}/{id}`
Staffel	`/v1/shows/tmdb/{id}/seasons/{n}` (Staffel 0 sind die Specials)
Musik	`/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}`

Unbekannte oder doppelte Parameter werden abgelehnt. IDs eines Anbieters werden nie für einen anderen verwendet.

Eine gute Antwort enthält schema_version, source, source_id, fetched_at, expires_at, completeness, stale und data. Behandle HTML in Zusammenfassungen als reinen Text.

Status	Bedeutung
400	Fehlerhafte Abfrage, nicht wiederholen
401	Falsches oder widerrufenes Token, nicht wiederholen
404	Kein solcher Eintrag
429	Zu viele Aufrufe, warte `Retry-After` ab
503	Ausgelastet, warte und versuche es einmal erneut