API HolyArrs

Z vlastných skriptov môžeš volať to isté JSON API, aké používa webová aplikácia, pod /api/v1.

Prvé volanie

1. Otvor Settings > API > API keys (Nastavenia > API > Kľúče API) a vytvor kľúč iba s rozsahmi, ktoré potrebuje. Skopíruj ho hneď, lebo sa zobrazí iba raz.
2. Pošli ho v hlavičke X-Api-Key pri každom volaní. Nikdy ho nevkladaj do adresy.
3. Volaj základnú adresu http://your-server:6262/api/v1. Pri URL base /holyarrs volaj 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"

Mal by si dostať JSON. Chyby majú tvar {"error": "plain words"} s HTTP stavom. Tajné údaje sa vrátia zamaskované.

Možnosti

Vyber rozsah

Rozsah	Povoľuje
health_read	Iba feed zdravia, pre monitorovacie nástroje
read	Trasy na čítanie vrátane feedu zdravia
write	Zmeny okrem trás pre admina a ovládania
admin	Ľudia, pozvánky, limity žiadostí, kľúče API, heslá a dvojfaktorové overenie, nastavenia prihlásenia, obnova
control	Prepínače častí, fázy, prepojené aplikácie, reštart a vypnutie
all	read, write a admin. Nie control

Monitorovaciemu nástroju daj health_read a nič iné.

Nájdi trasu

Settings > API (Nastavenia > API) ukazuje základnú adresu, rozsahy, ukážkové volania a každú trasu s jej rozsahom a oprávnením. Súbor OpenAPI je na /api/v1/openapi.json, keď si prihlásený. Trasy API uvádzajú každú trasu.

Komunikácia s HolyArrs ako so staršou aplikáciou

Seerr, Overseerr, Bazarr a podobné aplikácie toto API nepoužívajú. S HolyArrs komunikujú, ako keby to bol Sonarr a Radarr, s vlastnými kľúčmi. Pozri API starších aplikácií.

Ak to nefunguje

Príznak. 401 pri každom volaní. Príčina. Kľúč je nesprávny alebo vymazaný. Riešenie. Vytvor nový kľúč.

Príznak. 403 pri jednej trase. Príčina. Rozsah kľúča túto trasu nepokrýva. Riešenie. Skontroluj rozsah trasy v Settings > API.

Príznak. 404 pri každom volaní. Príčina. Chýba URL base. Riešenie. Daj ho pred /api/v1. Pozri URL base.

Pre expertov

Pridanie trasy

Trasy sú v súbore routes.go každého modulu. Každá je zaregistrovaná so svojou metódou, cestou a oprávnením, takže každá trasa má kontrolu oprávnenia.

openapi.json vzniká z trás. TestOpenAPIGenerated zlyhá, keď sa rozídu, preto ho aktualizuj v tej istej zmene. Snapshot tabuľky trás tiež zlyhá, keď sa trasa pridá, odstráni alebo presunie bez aktualizácie snapshotu.

Po vydaní cesty a názvy polí zostávajú. Polia pridávaj, nikdy ich nepremenúvaj. Po zmene spusti go run ./app/backend/tools/apidoc, aby sa prepísali Trasy API.

Volania metadátového servera

HolyArrs berie názvy, obrázky a ID z metadátového servera HolyArrs. Inštaláciu nasmeruješ na iný server pomocou HOLYARRS_METADATA_URL. Kód servera v tomto repozitári nie je.

Registrácia. Pri prvom vyhľadávaní inštalácia zavolá POST /v1/installations bez tela. Odpoveď je 201 s {"schema_version":1,"token":"hai_..."}. Aplikácia token uloží šifrovaný a pri každom vyhľadávaní posiela Authorization: Bearer <token>. Registruje sa iba raz. Po 401 sa už znova neregistruje, takže odvolaná inštalácia zostane odvolaná. Pri prekročení hodinového limitu pre skupinu adries je odpoveď 429 registration_limit s Retry-After.

Vyhľadávanie (všetko GET)	Trasa
Hľadanie	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
Film	/v1/movies/tmdb/{id}
Seriál	/v1/shows/{tmdb or tvmaze}/{id}
Séria	/v1/shows/tmdb/{id}/seasons/{n} (séria 0 sú špeciály)
Hudba	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

Neznáme alebo opakované parametre sa odmietnu. ID od jedného poskytovateľa sa nikdy nepoužijú pre iného.

Dobrá odpoveď obsahuje schema_version, source, source_id, fetched_at, expires_at, completeness, stale a data. HTML v súhrnoch ber ako obyčajný text.

Stav	Význam
400	Neplatná požiadavka, neskúšaj znova
401	Zlý alebo odvolaný token, neskúšaj znova
404	Taký záznam neexistuje
429	Príliš veľa volaní, počkaj na Retry-After
503	Server je vyťažený, počkaj a skús raz znova

Súvisiace stránky

• Trasy API
• API starších aplikácií
• Premenné prostredia