HolyArrsin API

Kutsu omista skripteistäsi samaa JSON-API:a, jota verkkosovellus käyttää, osoitteessa /api/v1.

Tee ensimmäinen kutsu

1. Avaa Settings > API > API keys (asetukset > API > API-avaimet) ja tee avain, jolla on vain tarvittavat oikeudet. Kopioi se heti, koska se näytetään vain kerran.
2. Lähetä se otsakkeessa X-Api-Key jokaisessa kutsussa. Älä koskaan laita sitä osoitteeseen.
3. Kutsu perusosoitetta http://your-server:6262/api/v1. Jos URL base on /holyarrs, kutsu osoitetta 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"

Saat vastaukseksi JSONia. Virheet tulevat muodossa {"error": "plain words"} ja HTTP-tilakoodin kanssa. Salaisuudet palautetaan peitettyinä.

Vaihtoehdot

Valitse oikeusalue

Oikeusalue	Sallii
health_read	Vain kuntosyötteen, valvontatyökaluja varten
read	Lukureitit, kuntosyöte mukaan lukien
write	Muutokset, paitsi ylläpitoreitit ja hallinta
admin	Käyttäjät, kutsut, pyyntörajat, API-avaimet, salasanat ja kaksivaiheinen tunnistautuminen, kirjautumisasetukset, palautus
control	Osien kytkimet, vaiheet, yhdistetyt sovellukset, uudelleenkäynnistys ja sammutus
all	read, write ja admin. Ei control

Anna valvontatyökalulle health_read eikä mitään muuta.

Etsi reitti

Settings > API näyttää perusosoitteen, oikeusalueet, esimerkkikutsut sekä jokaisen reitin oikeusalueen ja oikeuden. OpenAPI-tiedosto on osoitteessa /api/v1/openapi.json, kun olet kirjautunut sisään. Sivu API-reitit listaa kaikki reitit.

Keskustele HolyArrsin kanssa vanhan sovelluksen tapaan

Seerr, Overseerr, Bazarr ja vastaavat sovellukset eivät käytä tätä API:a. Ne puhuvat HolyArrsille kuin se olisi Sonarr ja Radarr, ja niillä on omat avaimensa. Katso Old-app API.

Jos se ei toimi

Oire. 401 jokaisessa kutsussa. Syy. Avain on väärä tai poistettu. Ratkaisu. Tee uusi avain.

Oire. 403 yhdellä reitillä. Syy. Avaimen oikeusalue ei kata sitä reittiä. Ratkaisu. Tarkista reitin oikeusalue sivulta Settings > API.

Oire. 404 jokaisessa kutsussa. Syy. URL base puuttuu. Ratkaisu. Laita se ennen osaa /api/v1. Katso URL base.

Asiantuntijoille

Lisää reitti

Reitit ovat kunkin moduulin tiedostossa routes.go. Jokainen rekisteröidään metodin, polun ja oikeuden kanssa, joten jokaisella reitillä on oikeustarkistus.

openapi.json syntyy reiteistä. TestOpenAPIGenerated epäonnistuu, jos ne eroavat toisistaan, joten päivitä se samassa muutoksessa. Reittitaulun tilannekuva epäonnistuu myös, kun reitti lisätään, poistetaan tai siirretään ilman tilannekuvan päivitystä.

Kun reitti on julkaistu, polut ja kenttien nimet pysyvät. Lisää kenttiä, älä koskaan nimeä niitä uudelleen. Muutoksen jälkeen aja go run ./app/backend/tools/apidoc, niin sivu API-reitit kirjoitetaan uudelleen.

Metadatapalvelimen kutsut

HolyArrs hakee nimet, kuvat ja tunnisteet HolyArrsin metadatapalvelimelta. Ohjaa asennus toiseen palvelimeen asetuksella HOLYARRS_METADATA_URL. Palvelimen koodi ei ole tässä repossa.

Rekisteröinti. Ensimmäisen haun yhteydessä asennus kutsuu POST /v1/installations ilman sisältöä. Vastaus on 201 ja {"schema_version":1,"token":"hai_..."}. Sovellus tallentaa tokenin salattuna ja lähettää Authorization: Bearer <token> jokaisessa haussa. Se rekisteröityy vain kerran. 401-vastauksen jälkeen se ei rekisteröidy uudelleen, joten peruttu asennus pysyy peruttuna. Jos osoiteryhmän tuntiraja ylittyy, vastaus on 429 registration_limit ja Retry-After.

Haku (kaikki GET)	Reitti
Haku	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
Elokuva	/v1/movies/tmdb/{id}
Sarja	/v1/shows/{tmdb or tvmaze}/{id}
Tuotantokausi	/v1/shows/tmdb/{id}/seasons/{n} (kausi 0 on erikoisjaksot)
Musiikki	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

Tuntemattomat tai toistuvat parametrit hylätään. Yhden tarjoajan tunnisteita ei koskaan käytetä toisen tarjoajan kanssa.

Onnistunut vastaus sisältää kentät schema_version, source, source_id, fetched_at, expires_at, completeness, stale ja data. Käsittele yhteenvedoissa oleva HTML pelkkänä tekstinä.

Tila	Merkitys
400	Virheellinen kysely, älä yritä uudelleen
401	Virheellinen tai peruttu token, älä yritä uudelleen
404	Tietuetta ei ole
429	Liikaa kutsuja, odota Retry-After-ajan verran
503	Kiireinen, odota ja yritä kerran uudelleen

Aiheesta lisää

• API-reitit
• Old-app API
• Ympäristömuuttujat