HolyArrs API

Kald det samme JSON-API, som web-appen bruger, under /api/v1, fra dine egne scripts.

Foretag dit første kald

1. Åbn Settings > API > API keys (indstillinger > API > API-nøgler) og lav en nøgle med kun de scopes, den har brug for. Kopiér den med det samme, for den vises kun én gang.
2. Send den i headeren X-Api-Key ved hvert kald. Skriv den aldrig i adressen.
3. Kald basisadressen http://your-server:6262/api/v1. Hvis du bruger URL base /holyarrs, kalder du 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"

Du bør få JSON tilbage. Fejl kommer som {"error": "plain words"} med en HTTP-status. Hemmeligheder kommer tilbage maskeret.

Valg

Vælg et scope

Scope	Tillader
health_read	Kun tilstandsfeedet, til overvågningsværktøjer
read	Læseruterne, inklusive tilstandsfeedet
write	Ændringer, undtagen adminruter og styring
admin	Personer, invitationer, ønskegrænser, API-nøgler, adgangskoder og tofaktor, login-indstillinger, gendannelse
control	Kontakter til dele, trin, forbundne apps, genstart og nedlukning
all	read, write og admin. Ikke control

Giv et overvågningsværktøj health_read og intet andet.

Find en rute

Settings > API viser basisadressen, scopes, eksempler på kald og alle ruter med deres scope og rettighed. OpenAPI-filen ligger på /api/v1/openapi.json, når du er logget ind. API-ruter viser alle ruter.

Tal med HolyArrs som en tidligere app

Seerr, Overseerr, Bazarr og lignende apps bruger ikke dette API. De taler med HolyArrs, som om det var Sonarr og Radarr, med deres egne nøgler. Se API til tidligere apps.

Hvis det ikke virker

Symptom. 401 ved hvert kald. Årsag. Nøglen er forkert eller slettet. Løsning. Lav en ny nøgle.

Symptom. 403 på én rute. Årsag. Nøglens scope dækker ikke den rute. Løsning. Tjek rutens scope under Settings > API.

Symptom. 404 ved hvert kald. Årsag. URL base mangler. Løsning. Sæt den foran /api/v1. Se URL base.

For erfarne

Tilføj en rute

Ruter ligger i hvert moduls routes.go. Hver rute registreres med sin metode, sti og rettighed, så alle ruter har et rettighedstjek.

openapi.json bliver lavet ud fra ruterne. TestOpenAPIGenerated fejler, når de ikke passer sammen, så opdater den i samme ændring. Et snapshot af rutetabellen fejler også, når en rute tilføjes, fjernes eller flyttes uden en opdatering af snapshottet.

Når en sti eller et feltnavn er udgivet, bliver den stående. Tilføj felter, omdøb dem aldrig. Efter en ændring kører du go run ./app/backend/tools/apidoc for at skrive API-ruter om.

Kald til metadataserveren

HolyArrs henter navne, billeder og id’er fra HolyArrs’ metadataserver. Peg en installation på en anden server med HOLYARRS_METADATA_URL. Serverkoden er ikke i dette repo.

Registrering. Ved sit første opslag kalder en installation POST /v1/installations uden body. Svaret er 201 med {"schema_version":1,"token":"hai_..."}. Appen gemmer tokenet krypteret og sender Authorization: Bearer <token> ved hvert opslag. Den registrerer sig kun én gang. Efter en 401 registrerer den sig ikke igen, så en tilbagekaldt installation forbliver tilbagekaldt. Over timegrænsen pr. adressegruppe er svaret 429 registration_limit med Retry-After.

Opslag (alle GET)	Rute
Søgning	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
Film	/v1/movies/tmdb/{id}
Serie	/v1/shows/{tmdb or tvmaze}/{id}
Sæson	/v1/shows/tmdb/{id}/seasons/{n} (sæson 0 er specials)
Musik	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

Ukendte eller gentagne parametre afvises. Id’er fra én udbyder bruges aldrig hos en anden.

Et godt svar har schema_version, source, source_id, fetched_at, expires_at, completeness, stale og data. Behandl HTML i resuméer som almindelig tekst.

Status	Betyder
400	Ugyldig forespørgsel, forsøg ikke igen
401	Ugyldigt eller tilbagekaldt token, forsøg ikke igen
404	Posten findes ikke
429	For mange kald, vent på Retry-After
503	Serveren er travl, vent og forsøg én gang til

Se også

• API-ruter
• API til tidligere apps
• Miljøvariabler