HolyArrs API

Iz vlastitih skripti pozivaj isti JSON API koji koristi i web aplikacija, na putanji /api/v1.

Prvi poziv

1. Otvori Settings > API > API keys (Postavke > API > API ključevi) i napravi ključ samo s opsezima koji su mu potrebni. Kopiraj ga odmah, jer se prikazuje samo jednom.
2. Šalji ga u zaglavlju X-Api-Key u svakom pozivu. Nikada ga ne stavljaj u adresu.
3. Pozivaj osnovnu adresu http://your-server:6262/api/v1. Ako je URL base /holyarrs, pozivaj 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"

Dobit ćeš JSON. Greške izgledaju ovako: {"error": "plain words"}, uz HTTP status. Tajne se vraćaju maskirane.

Izbori

Odaberi opseg

Opseg	Dopušta
health_read	Samo feed stanja, za alate za nadzor
read	Rute za čitanje, uključujući feed stanja
write	Promjene, osim admin ruta i upravljanja
admin	Korisnici, pozivnice, ograničenja zahtjeva, API ključevi, lozinke i dvofaktorska prijava, postavke prijave, vraćanje iz backupa
control	Prekidači dijelova, faze, povezane aplikacije, ponovno pokretanje i gašenje
all	read, write i admin. Bez control

Alatu za nadzor daj health_read i ništa drugo.

Pronađi rutu

Settings > API (Postavke > API) prikazuje osnovnu adresu, opsege, primjere poziva i svaku rutu s njezinim opsegom i dozvolom. OpenAPI datoteka nalazi se na /api/v1/openapi.json kad si prijavljen. API rute navode svaku rutu.

Razgovaraj s HolyArrs kao s dosadašnjom aplikacijom

Seerr, Overseerr, Bazarr i slične aplikacije ne koriste ovaj API. One s HolyArrs razgovaraju kao da je Sonarr i Radarr, s vlastitim ključevima. Pogledaj API za dosadašnje aplikacije.

Ako ne radi

Simptom. 401 na svakom pozivu. Uzrok. Ključ je pogrešan ili izbrisan. Rješenje. Napravi novi ključ.

Simptom. 403 na jednoj ruti. Uzrok. Opseg ključa ne pokriva tu rutu. Rješenje. Provjeri opseg rute na Settings > API.

Simptom. 404 na svakom pozivu. Uzrok. Nedostaje URL base. Rješenje. Stavi ga ispred /api/v1. Pogledaj URL base.

Za napredne

Dodaj rutu

Rute se nalaze u datoteci routes.go svakog modula. Svaka se registrira s metodom, putanjom i dozvolom, pa svaka ruta ima provjeru dozvole.

openapi.json nastaje iz ruta. TestOpenAPIGenerated pada kad se razilaze, zato ga ažuriraj u istoj promjeni. Snimka tablice ruta također pada kad se ruta doda, ukloni ili premjesti bez ažuriranja snimke.

Nakon izlaska verzije putanje i imena polja ostaju ista. Polja dodaj, nikada ih ne preimenuj. Nakon promjene izvrši go run ./app/backend/tools/apidoc da ponovno napišeš API rute.

Pozivi metadata servera

HolyArrs imena, slike i ID-eve dobiva s HolyArrs metadata servera. Instalaciju možeš usmjeriti na drugi server pomoću HOLYARRS_METADATA_URL. Kod servera nije u ovom repou.

Registracija. Pri prvom upitu instalacija poziva POST /v1/installations bez tijela. Odgovor je 201 s {"schema_version":1,"token":"hai_..."}. Aplikacija sprema token šifriran i šalje Authorization: Bearer <token> u svakom upitu. Registrira se samo jednom. Nakon 401 ne registrira se ponovno, pa opozvana instalacija ostaje opozvana. Ako se prijeđe satno ograničenje po grupi adresa, odgovor je 429 registration_limit s Retry-After.

Upit (svi GET)	Ruta
Pretraga	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
Film	/v1/movies/tmdb/{id}
Serija	/v1/shows/{tmdb or tvmaze}/{id}
Sezona	/v1/shows/tmdb/{id}/seasons/{n} (sezona 0 su specijali)
Glazba	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

Nepoznati ili ponovljeni parametri odbijaju se. ID-evi jednog providera nikada se ne koriste za drugog.

Dobar odgovor sadrži schema_version, source, source_id, fetched_at, expires_at, completeness, stale i data. HTML u sažecima tretiraj kao običan tekst.

Status	Znači
400	Loš upit, ne pokušavaj ponovno
401	Loš ili opozvan token, ne pokušavaj ponovno
404	Nema takvog zapisa
429	Previše poziva, pričekaj Retry-After
503	Zauzeto, pričekaj i pokušaj jednom ponovno

Povezane stranice

• API rute
• API za dosadašnje aplikacije
• Varijable okoline