API HolyArrs

Z vlastních skriptů můžeš volat stejné JSON API, které používá webová aplikace, pod cestou /api/v1.

První volání

1. Otevři Settings > API > API keys (nastavení > API > klíče API) a vytvoř klíč jen s rozsahy, které potřebuje. Hned si ho zkopíruj, zobrazí se jen jednou.
2. Posílej ho v hlavičce X-Api-Key při každém volání. Nikdy ho nevkládej do adresy.
3. Volej základní adresu http://your-server:6262/api/v1. Při URL base /holyarrs volej 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"

Měl bys dostat zpět JSON. Chyby mají tvar {"error": "plain words"} a HTTP stav. Tajné údaje se vracejí zamaskované.

Možnosti

Vyber rozsah

Rozsah	Povoluje
health_read	Jen feed zdraví, pro monitorovací nástroje
read	Trasy pro čtení, včetně feedu zdraví
write	Změny, kromě tras správce a ovládání
admin	Lidé, pozvánky, limity žádostí, API klíče, hesla a dvoufázové ověření, nastavení přihlášení, obnova
control	Přepínače částí, fáze, propojené aplikace, restart a vypnutí
all	read, write a admin. Ne control

Monitorovacímu nástroji dej health_read a nic dalšího.

Najdi trasu

Settings > API ukazuje základní adresu, rozsahy, příklady volání a všechny trasy s jejich rozsahem a oprávněním. Soubor OpenAPI je na /api/v1/openapi.json, když jsi přihlášený. Trasy API vypisují všechny trasy.

Mluv s HolyArrs jako dřívější aplikace

Seerr, Overseerr, Bazarr a podobné aplikace toto API nepoužívají. S HolyArrs mluví, jako by byl Sonarr a Radarr, a mají vlastní klíče. Viz API dřívějších aplikací.

Když to nefunguje

Příznak. 401 při každém volání. Příčina. Klíč je špatný nebo smazaný. Řešení. Vytvoř nový klíč.

Příznak. 403 u jedné trasy. Příčina. Rozsah klíče tuto trasu nepokrývá. Řešení. Zkontroluj rozsah trasy v Settings > API.

Příznak. 404 při každém volání. Příčina. Chybí URL base. Řešení. Dej ji před /api/v1. Viz URL base.

Pro pokročilé

Přidání trasy

Trasy jsou v souboru routes.go každého modulu. Každá se registruje se svou metodou, cestou a oprávněním, takže každá trasa má kontrolu oprávnění.

openapi.json vzniká z tras. TestOpenAPIGenerated selže, když se rozejdou, proto ho aktualizuj ve stejné změně. Snímek tabulky tras také selže, když se trasa přidá, odebere nebo přesune bez aktualizace snímku.

Po vydání cesty a názvy polí zůstávají. Pole přidávej, nikdy je nepřejmenovávej. Po změně spusť go run ./app/backend/tools/apidoc, aby se přepsaly trasy API.

Volání metadata serveru

HolyArrs bere názvy, obrázky a id z metadata serveru HolyArrs. Instalaci nasměruješ na jiný server pomocí HOLYARRS_METADATA_URL. Kód serveru v tomto repozitáři není.

Registrace. Při prvním dotazu volá instalace POST /v1/installations bez těla. Odpověď je 201 s {"schema_version":1,"token":"hai_..."}. Aplikace token uloží zašifrovaný a při každém dotazu posílá Authorization: Bearer <token>. Registruje se jen jednou. Po 401 se znovu neregistruje, takže odvolaná instalace zůstane odvolaná. Při překročení hodinového limitu pro skupinu adres je odpověď 429 registration_limit s Retry-After.

Dotaz (všechny GET)	Trasa
Hledání	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
Film	/v1/movies/tmdb/{id}
Seriál	/v1/shows/{tmdb or tvmaze}/{id}
Řada	/v1/shows/tmdb/{id}/seasons/{n} (řada 0 jsou speciály)
Hudba	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

Neznámé nebo opakované parametry se odmítnou. Id od jednoho poskytovatele se nikdy nepoužijí u jiného.

Dobrá odpověď má schema_version, source, source_id, fetched_at, expires_at, completeness, stale a data. HTML v popisech ber jako prostý text.

Stav	Význam
400	Špatný dotaz, nezkoušej znovu
401	Špatný nebo odvolaný token, nezkoušej znovu
404	Takový záznam není
429	Příliš mnoho volání, počkej na Retry-After
503	Server je vytížený, počkej a zkus jednou znovu

Související

• Trasy API
• API dřívějších aplikací
• Proměnné prostředí