HolyArrs-API-et

Kall det samme JSON-API-et som web-appen bruker, under /api/v1, fra dine egne skript.

Gjør det første kallet

1. Åpne Settings > API > API keys (innstillinger > API > API-nøkler) og lag en nøkkel med bare de tilgangene den trenger. Kopier den med en gang, for den vises bare én gang.
2. Send den i headeren X-Api-Key på hvert kall. Skriv den aldri i adressen.
3. Kall basisadressen http://your-server:6262/api/v1. Med en URL base på /holyarrs kaller 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 skal få JSON tilbake. Feil kommer som {"error": "plain words"} med en HTTP-status. Hemmeligheter kommer tilbake maskert.

Valg

Velg en tilgang

Tilgang	Tillater
health_read	Bare helsefeeden, for overvåkingsverktøy
read	Leserutene, helsefeeden inkludert
write	Endringer, unntatt admin-ruter og kontroller
admin	Personer, invitasjoner, forespørselsgrenser, API-nøkler, passord og tofaktor, innstillinger for innlogging, gjenoppretting
control	Brytere for deler, trinn, tilkoblede apper, omstart og avslutning
all	read, write og admin. Ikke control

Gi et overvåkingsverktøy health_read og ingenting annet.

Finn en rute

Settings > API viser basisadressen, tilgangene, eksempelkall og hver rute med tilgang og tillatelse. OpenAPI-filen ligger på /api/v1/openapi.json når du er logget inn. API-ruter lister opp alle rutene.

Snakk med HolyArrs som en tidligere app

Seerr, Overseerr, Bazarr og lignende apper bruker ikke dette API-et. De snakker med HolyArrs som om det var Sonarr og Radarr, med egne nøkler. Se API for tidligere apper.

Hvis det ikke fungerer

Symptom. 401 på hvert kall. Årsak. Nøkkelen er feil eller slettet. Løsning. Lag en ny nøkkel.

Symptom. 403 på én rute. Årsak. Tilgangen til nøkkelen dekker ikke den ruten. Løsning. Sjekk tilgangen til ruten på Settings > API.

Symptom. 404 på hvert kall. Årsak. URL basen mangler. Løsning. Sett den foran /api/v1. Se URL base.

For viderekomne

Legg til en rute

Rutene ligger i routes.go i hver modul. Hver rute registreres med metode, sti og tillatelse, så alle ruter har en tillatelsessjekk.

openapi.json kommer fra rutene. TestOpenAPIGenerated feiler når de ikke stemmer overens, så oppdater den i samme endring. Et snapshot av rutetabellen feiler også når en rute legges til, fjernes eller flyttes uten at snapshotet oppdateres.

Etter at en versjon er sluppet, ligger stier og feltnavn fast. Legg til felt, men gi aldri nytt navn til eksisterende felt. Etter en endring kjører du go run ./app/backend/tools/apidoc for å skrive om API-ruter.

Kall mot metadataserveren

HolyArrs henter navn, bilder og id-er fra HolyArrs-metadataserveren. Pek en installasjon mot en annen server med HOLYARRS_METADATA_URL. Serverkoden ligger ikke i dette repoet.

Registrering. Ved det første oppslaget kaller en installasjon POST /v1/installations uten body. Svaret er 201 med {"schema_version":1,"token":"hai_..."}. Appen lagrer tokenet kryptert og sender Authorization: Bearer <token> på hvert oppslag. Den registrerer seg én gang. Etter en 401 registrerer den seg ikke på nytt, så en installasjon som er trukket tilbake, forblir tilbaketrukket. Over timegrensen per adressegruppe er svaret 429 registration_limit med Retry-After.

Oppslag (alle GET)	Rute
Søk	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
Film	/v1/movies/tmdb/{id}
Serie	/v1/shows/{tmdb or tvmaze}/{id}
Sesong	/v1/shows/tmdb/{id}/seasons/{n} (sesong 0 er spesialepisoder)
Musikk	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

Ukjente eller gjentatte parametere blir avvist. Id-er fra én leverandør brukes aldri for en annen.

Et godt svar har schema_version, source, source_id, fetched_at, expires_at, completeness, stale og data. Behandle HTML i sammendrag som ren tekst.

Status	Betyr
400	Ugyldig spørring, ikke prøv igjen
401	Ugyldig eller tilbaketrukket token, ikke prøv igjen
404	Oppføringen finnes ikke
429	For mange kall, vent på Retry-After
503	Opptatt, vent og prøv én gang til

Relatert

• API-ruter
• API for tidligere apper
• Miljøvariabler