De HolyArrs-API

Roep vanuit je eigen scripts dezelfde JSON-API aan als de web-app, onder /api/v1.

Je eerste aanroep doen

1. Open Settings > API > API keys (instellingen > API > API-sleutels) en maak een sleutel met alleen de scopes die hij nodig heeft. Kopieer hem meteen, want hij wordt maar één keer getoond.
2. Stuur hem bij elke aanroep mee in de header X-Api-Key. Zet hem nooit in het adres.
3. Roep het basisadres http://your-server:6262/api/v1 aan. Bij een URL base van /holyarrs roep je http://your-server:6262/holyarrs/api/v1 aan.

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

Je krijgt JSON terug. Fouten zijn {"error": "plain words"} met een HTTP-status. Geheimen komen gemaskeerd terug.

Keuzes

Een scope kiezen

Scope	Staat toe
health_read	Alleen de gezondheidsfeed, voor monitoringtools
read	De leesroutes, inclusief de gezondheidsfeed
write	Wijzigingen, behalve beheerroutes en bediening
admin	Mensen, uitnodigingen, aanvraaglimieten, API-sleutels, wachtwoorden en tweestapsverificatie, aanmeldinstellingen, terugzetten
control	Schakelaars voor onderdelen, fases, gekoppelde apps, herstarten en afsluiten
all	read, write en admin. Niet control

Geef een monitoringtool health_read en niets anders.

Een route vinden

Settings > API toont het basisadres, de scopes, voorbeeldaanroepen en elke route met zijn scope en recht. Het OpenAPI-bestand staat op /api/v1/openapi.json als je bent aangemeld. API-routes toont alle routes.

Met HolyArrs praten als een eerdere app

Seerr, Overseerr, Bazarr en vergelijkbare apps gebruiken deze API niet. Zij praten met HolyArrs alsof het Sonarr en Radarr is, met eigen sleutels. Zie API voor eerdere apps.

Als het niet werkt

Symptoom. 401 bij elke aanroep. Oorzaak. De sleutel is verkeerd of verwijderd. Oplossing. Maak een nieuwe sleutel.

Symptoom. 403 bij één route. Oorzaak. De scope van de sleutel dekt die route niet. Oplossing. Controleer de scope van de route bij Settings > API.

Symptoom. 404 bij elke aanroep. Oorzaak. De URL base ontbreekt. Oplossing. Zet hem vóór /api/v1. Zie URL base.

Voor gevorderden

Een route toevoegen

Routes staan in het routes.go van elke module. Elke route wordt geregistreerd met zijn methode, pad en recht, dus elke route heeft een rechtencontrole.

openapi.json komt uit de routes. TestOpenAPIGenerated mislukt als ze uit de pas lopen, dus werk het in dezelfde wijziging bij. Ook een snapshot van de routetabel mislukt als een route wordt toegevoegd, verwijderd of verplaatst zonder dat de snapshot is bijgewerkt.

Na de release blijven paden en veldnamen zoals ze zijn. Voeg velden toe, hernoem ze nooit. Voer na een wijziging go run ./app/backend/tools/apidoc uit om API-routes opnieuw te schrijven.

Aanroepen naar de metadataserver

HolyArrs haalt namen, afbeeldingen en id’s op bij de HolyArrs-metadataserver. Wijs een installatie naar een andere server met HOLYARRS_METADATA_URL. De servercode staat niet in deze repo.

Registratie. Bij zijn eerste opzoeking roept een installatie POST /v1/installations aan zonder body. Het antwoord is 201 met {"schema_version":1,"token":"hai_..."}. De app slaat de token versleuteld op en stuurt bij elke opzoeking Authorization: Bearer <token> mee. Hij registreert maar één keer. Na een 401 registreert hij niet opnieuw, dus een ingetrokken installatie blijft ingetrokken. Boven de limiet per uur voor een adresgroep is het antwoord 429 registration_limit met Retry-After.

Opzoeking (allemaal GET)	Route
Zoeken	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
Film	/v1/movies/tmdb/{id}
Serie	/v1/shows/{tmdb or tvmaze}/{id}
Seizoen	/v1/shows/tmdb/{id}/seasons/{n} (seizoen 0 zijn specials)
Muziek	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

Onbekende of herhaalde parameters worden geweigerd. Id’s van de ene provider worden nooit voor een andere gebruikt.

Een goed antwoord heeft schema_version, source, source_id, fetched_at, expires_at, completeness, stale en data. Behandel HTML in samenvattingen als gewone tekst.

Status	Betekent
400	Foute query, niet opnieuw proberen
401	Foute of ingetrokken token, niet opnieuw proberen
404	Zo’n record bestaat niet
429	Te veel aanroepen, wacht op Retry-After
503	Druk, wacht en probeer één keer opnieuw

Gerelateerde pagina’s

• API-routes
• API voor eerdere apps
• Omgevingsvariabelen