API HolyArrs

Wywołuj z własnych skryptów to samo API JSON, z którego korzysta aplikacja webowa, pod adresem /api/v1.

Pierwsze wywołanie

1. Otwórz Settings > API > API keys (ustawienia > API > klucze API) i utwórz klucz tylko z tymi zakresami, których potrzebujesz. Skopiuj go od razu, bo pokazuje się tylko raz.
2. Wysyłaj go w nagłówku X-Api-Key przy każdym wywołaniu. Nigdy nie wpisuj go w adresie.
3. Wywołuj adres bazowy http://your-server:6262/api/v1. Przy URL base ustawionym na /holyarrs wywołuj 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"

Dostaniesz w odpowiedzi JSON. Błędy mają postać {"error": "plain words"} z kodem statusu HTTP. Sekrety wracają zamaskowane.

Opcje

Wybierz zakres

Zakres	Pozwala na
health_read	Tylko kanał kondycji, dla narzędzi do monitoringu
read	Trasy do odczytu, razem z kanałem kondycji
write	Zmiany, oprócz tras administracyjnych i sterujących
admin	Osoby, zaproszenia, limity próśb, klucze API, hasła i uwierzytelnianie dwuskładnikowe, ustawienia logowania, przywracanie
control	Przełączniki modułów, etapy, połączone aplikacje, restart i wyłączanie
all	read, write i admin. Bez control

Narzędziu do monitoringu daj health_read i nic więcej.

Znajdź trasę

Settings > API pokazuje adres bazowy, zakresy, przykładowe wywołania oraz każdą trasę z jej zakresem i uprawnieniem. Plik OpenAPI jest pod /api/v1/openapi.json, gdy jesteś zalogowany. Trasy API wymieniają każdą trasę.

Połącz się z HolyArrs jak dotychczasowa aplikacja

Seerr, Overseerr, Bazarr i podobne aplikacje nie używają tego API. Łączą się z HolyArrs tak, jakby to były Sonarr i Radarr, z własnymi kluczami. Zobacz API dla dotychczasowych aplikacji.

Jeśli to nie działa

Objaw. Błąd 401 przy każdym wywołaniu. Przyczyna. Klucz jest błędny albo usunięty. Rozwiązanie. Utwórz nowy klucz.

Objaw. Błąd 403 na jednej trasie. Przyczyna. Zakres klucza nie obejmuje tej trasy. Rozwiązanie. Sprawdź zakres trasy w Settings > API.

Objaw. Błąd 404 przy każdym wywołaniu. Przyczyna. Brakuje URL base. Rozwiązanie. Wstaw go przed /api/v1. Zobacz URL base.

Dla zaawansowanych

Dodawanie trasy

Trasy są w pliku routes.go każdego modułu. Każda jest rejestrowana z metodą, ścieżką i uprawnieniem, więc każda trasa ma kontrolę uprawnień.

openapi.json powstaje z tras. TestOpenAPIGenerated zawodzi, gdy się rozjadą, więc zaktualizuj go w tej samej zmianie. Snapshot tabeli tras też zawodzi, gdy trasa zostanie dodana, usunięta albo przeniesiona bez aktualizacji snapshotu.

Po wydaniu ścieżki i nazwy pól zostają. Dodawaj pola, nigdy nie zmieniaj ich nazw. Po zmianie wykonaj go run ./app/backend/tools/apidoc, żeby przepisać Trasy API.

Wywołania serwera metadanych

HolyArrs pobiera nazwy, obrazki i identyfikatory z serwera metadanych HolyArrs. Żeby instalacja korzystała z innego serwera, ustaw HOLYARRS_METADATA_URL. Kodu serwera nie ma w tym repozytorium.

Rejestracja. Przy pierwszym wyszukiwaniu instalacja wywołuje POST /v1/installations bez treści. Odpowiedź to 201 z {"schema_version":1,"token":"hai_..."}. Aplikacja zapisuje token zaszyfrowany i wysyła Authorization: Bearer <token> przy każdym wyszukiwaniu. Rejestruje się raz. Po 401 nie rejestruje się ponownie, więc odwołana instalacja zostaje odwołana. Po przekroczeniu godzinnego limitu na grupę adresów odpowiedź to 429 registration_limit z Retry-After.

Wyszukiwanie (wszystko GET)	Trasa
Wyszukiwanie	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
Film	/v1/movies/tmdb/{id}
Serial	/v1/shows/{tmdb or tvmaze}/{id}
Sezon	/v1/shows/tmdb/{id}/seasons/{n} (sezon 0 to odcinki specjalne)
Muzyka	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

Nieznane albo powtórzone parametry są odrzucane. Identyfikatory od jednego dostawcy nigdy nie są używane u innego.

Poprawna odpowiedź zawiera schema_version, source, source_id, fetched_at, expires_at, completeness, stale i data. Traktuj HTML w opisach jako zwykły tekst.

Status	Znaczy
400	Złe zapytanie, nie ponawiaj
401	Zły albo odwołany token, nie ponawiaj
404	Nie ma takiego rekordu
429	Za dużo wywołań, poczekaj na Retry-After
503	Zajęty, poczekaj i spróbuj raz jeszcze

Powiązane strony

• Trasy API
• API dla dotychczasowych aplikacji
• Zmienne środowiskowe