HolyArrs API

Anropa samma JSON-API som webbappen använder, under /api/v1, från dina egna skript.

Gör ditt första anrop

1. Öppna Settings > API > API keys (inställningar > API > API-nycklar) och skapa en nyckel med bara de behörighetsnivåer den behöver. Kopiera den direkt, eftersom den bara visas en gång.
2. Skicka den i headern X-Api-Key vid varje anrop. Lägg den aldrig i adressen.
3. Anropa basadressen http://your-server:6262/api/v1. Med en URL base på /holyarrs anropar 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 ska få JSON tillbaka. Fel kommer som {"error": "plain words"} med en HTTP-status. Hemligheter kommer tillbaka maskerade.

Val

Välj en behörighetsnivå

Nivå	Tillåter
health_read	Bara hälsoflödet, för övervakningsverktyg
read	Läs-routes, hälsoflödet inkluderat
write	Ändringar, utom admin-routes och styrning
admin	Personer, inbjudningar, förfrågningsgränser, API-nycklar, lösenord och tvåfaktor, inloggningsinställningar, återställning
control	Reglage för delar, steg, länkade appar, omstart och avstängning
all	read, write och admin. Inte control

Ge ett övervakningsverktyg health_read och inget annat.

Hitta en route

Settings > API visar basadressen, behörighetsnivåerna, exempelanrop och varje route med sin nivå och behörighet. OpenAPI-filen finns på /api/v1/openapi.json när du är inloggad. API-routes listar varje route.

Prata med HolyArrs som en tidigare app

Seerr, Overseerr, Bazarr och liknande appar använder inte det här API:et. De pratar med HolyArrs som om det vore Sonarr och Radarr, med egna nycklar. Se API för tidigare appar.

Om det inte fungerar

Symptom. 401 på varje anrop. Orsak. Nyckeln är fel eller raderad. Lösning. Skapa en ny nyckel.

Symptom. 403 på en route. Orsak. Nyckelns nivå täcker inte den routen. Lösning. Kontrollera routens nivå under Settings > API.

Symptom. 404 på varje anrop. Orsak. URL base saknas. Lösning. Lägg den före /api/v1. Se URL base.

För experter

Lägg till en route

Routes finns i varje moduls routes.go. Varje route registreras med sin metod, sökväg och behörighet, så varje route har en behörighetskontroll.

openapi.json genereras från routes. TestOpenAPIGenerated misslyckas när de glider isär, så uppdatera den i samma ändring. Även en ögonblicksbild av route-tabellen misslyckas när en route läggs till, tas bort eller flyttas utan att ögonblicksbilden uppdateras.

När en route väl har släppts ligger sökvägar och fältnamn fast. Lägg till fält, byt aldrig namn på dem. Efter en ändring kör du go run ./app/backend/tools/apidoc för att skriva om API-routes.

Anrop till metadataservern

HolyArrs hämtar namn, bilder och id:n från HolyArrs metadataserver. Peka en installation mot en annan server med HOLYARRS_METADATA_URL. Serverkoden finns inte i det här repot.

Registrering. Vid sitt första uppslag anropar en installation POST /v1/installations utan body. Svaret är 201 med {"schema_version":1,"token":"hai_..."}. Appen sparar token krypterad och skickar Authorization: Bearer <token> vid varje uppslag. Den registrerar sig en gång. Efter en 401 registrerar den sig inte igen, så en återkallad installation förblir återkallad. Över timgränsen per adressgrupp blir svaret 429 registration_limit med Retry-After.

Uppslag (alla GET)	Route
Sökning	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
Film	/v1/movies/tmdb/{id}
Serie	/v1/shows/{tmdb or tvmaze}/{id}
Säsong	/v1/shows/tmdb/{id}/seasons/{n} (säsong 0 är specialavsnitt)
Musik	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

Okända eller upprepade parametrar avvisas. Id:n från en leverantör används aldrig för en annan.

Ett bra svar har schema_version, source, source_id, fetched_at, expires_at, completeness, stale och data. Behandla HTML i sammanfattningar som vanlig text.

Status	Betyder
400	Felaktig fråga, försök inte igen
401	Felaktig eller återkallad token, försök inte igen
404	Posten finns inte
429	För många anrop, vänta på Retry-After
503	Upptagen, vänta och försök en gång till

Relaterat

• API-routes
• API för tidigare appar
• Miljövariabler