HolyArrs API

Kallaðu á sama JSON API og vefviðmótið notar, undir /api/v1, úr þínum eigin skriftum.

Fyrsta kallið

1. Opnaðu Settings > API > API keys (stillingar > API > API-lyklar) og búðu til lykil með aðeins þeim umfangsgildum sem hann þarf. Afritaðu hann strax, því hann birtist bara einu sinni.
2. Sendu hann í hausnum X-Api-Key í hverju kalli. Settu hann aldrei í vistfangið.
3. Kallaðu á grunnvistfangið http://your-server:6262/api/v1. Ef URL-grunnurinn er /holyarrs skaltu kalla á 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"

Þú ættir að fá JSON til baka. Villur eru á forminu {"error": "plain words"} ásamt HTTP-stöðu. Leyndarmál koma til baka falin.

Valkostir

Veldu umfang

Umfang	Leyfir
health_read	Aðeins heilsustrauminn, fyrir vöktunarforrit
read	Lesleiðirnar, þar með talinn heilsustraumurinn
write	Breytingar, nema stjórnandaleiðir og stýringar
admin	Fólk, boð, takmörk á beiðnum, API-lykla, lykilorð og tveggja þrepa auðkenningu, stillingar innskráningar, endurheimt
control	Rofa fyrir hluta, áfanga, tengd forrit, endurræsingu og slökkvun
all	read, write og admin. Ekki control

Gefðu vöktunarforriti health_read og ekkert annað.

Finndu leið

Settings > API sýnir grunnvistfangið, umfangsgildin, dæmi um köll og allar leiðir með umfangi þeirra og heimild. OpenAPI-skráin er á /api/v1/openapi.json þegar þú skráir þig inn. API-leiðir telur upp allar leiðir.

Tala við HolyArrs sem eldra forrit

Seerr, Overseerr, Bazarr og áþekk forrit nota ekki þennan API. Þau tala við HolyArrs eins og það væri Sonarr og Radarr, með sína eigin lykla. Sjá API fyrir eldri forrit.

Ef það virkar ekki

Einkenni. 401 í hverju kalli. Orsök. Lykillinn er rangur eða hefur verið eytt. Lausn. Búðu til nýjan lykil.

Einkenni. 403 á einni leið. Orsök. Umfang lykilsins nær ekki yfir þá leið. Lausn. Athugaðu umfang leiðarinnar á Settings > API.

Einkenni. 404 í hverju kalli. Orsök. URL-grunninn vantar. Lausn. Settu hann á undan /api/v1. Sjá URL-grunnur.

Fyrir sérfræðinga

Bæta við leið

Leiðir eru í routes.go í hverri einingu. Hver þeirra er skráð með aðferð, slóð og heimild, svo hver leið hefur heimildarathugun.

openapi.json er búin til út frá leiðunum. TestOpenAPIGenerated fellur þegar þetta tvennt fer úr takt, svo uppfærðu hana í sömu breytingu. Skyndimynd af leiðatöflunni fellur líka þegar leið er bætt við, fjarlægð eða færð án þess að skyndimyndin sé uppfærð.

Þegar leið hefur verið gefin út standa slóðir og heiti reita óbreytt. Bættu við reitum, endurnefndu þá aldrei. Eftir breytingu skaltu keyra go run ./app/backend/tools/apidoc til að endurskrifa API-leiðir.

Köll á metadata-server

HolyArrs sækir nöfn, myndir og auðkenni frá metadata-server HolyArrs. Beindu uppsetningu á annan server með HOLYARRS_METADATA_URL. Kóði serversins er ekki í þessu repo.

Skráning. Í fyrstu uppflettingu kallar uppsetning á POST /v1/installations án texta í beiðninni. Svarið er 201 með {"schema_version":1,"token":"hai_..."}. Forritið geymir token dulkóðað og sendir Authorization: Bearer <token> í hverri uppflettingu. Það skráir sig einu sinni. Eftir 401 skráir það sig ekki aftur, svo afturkölluð uppsetning helst afturkölluð. Fari fjöldinn yfir takmörkin á klukkustund fyrir hvern vistfangahóp er svarið 429 registration_limit með Retry-After.

Uppflettingar (allar GET)	Leið
Leit	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
Kvikmynd	/v1/movies/tmdb/{id}
Þættir	/v1/shows/{tmdb or tvmaze}/{id}
Þáttaröð	/v1/shows/tmdb/{id}/seasons/{n} (þáttaröð 0 eru sérþættir)
Tónlist	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

Óþekktum eða endurteknum stikum er hafnað. Auðkenni frá einum veitanda eru aldrei notuð hjá öðrum.

Gott svar hefur schema_version, source, source_id, fetched_at, expires_at, completeness, stale og data. Meðhöndlaðu HTML í samantektum sem venjulegan texta.

Staða	Merking
400	Léleg fyrirspurn, ekki reyna aftur
401	Rangt eða afturkallað token, ekki reyna aftur
404	Engin slík færsla
429	Of mörg köll, bíddu eftir Retry-After
503	Of mikið álag, bíddu og reyndu einu sinni aftur

Tengt efni

• API-leiðir
• API fyrir eldri forrit
• Umhverfisbreytur