L'API d'HolyArrs

Crida des dels teus scripts la mateixa API JSON que fa servir l’app web, sota /api/v1.

Fes la teva primera crida

1. Obre Settings > API > API keys (Paràmetres > API > claus d’API) i crea una clau només amb els àmbits que necessita. Copia-la ara, perquè només es mostra una vegada.
2. Envia-la a la capçalera X-Api-Key a cada crida. No la posis mai a l’adreça.
3. Crida l’adreça base http://your-server:6262/api/v1. Amb una URL base de /holyarrs, crida 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"

Hauries de rebre JSON. Els errors són {"error": "plain words"} amb un estat HTTP. Els secrets tornen emmascarats.

Opcions

Tria un àmbit

Àmbit	Permet
health_read	Només el feed de salut, per a eines de monitoratge
read	Les rutes de lectura, inclòs el feed de salut
write	Canvis, tret de les rutes d’administració i els controls
admin	Persones, invitacions, límits de sol·licituds, claus d’API, contrasenyes i dos factors, paràmetres d’inici de sessió, restauració
control	Interruptors de les parts, etapes, apps enllaçades, reiniciar i aturar
all	read, write i admin. No control

A una eina de monitoratge dona-li health_read i res més.

Troba una ruta

Settings > API mostra l’adreça base, els àmbits, exemples de crides i totes les rutes amb el seu àmbit i permís. El fitxer OpenAPI és a /api/v1/openapi.json quan has iniciat la sessió. Rutes de l’API llista totes les rutes.

Parla amb HolyArrs com una app anterior

Seerr, Overseerr, Bazarr i apps semblants no fan servir aquesta API. Parlen amb HolyArrs com si fos Sonarr i Radarr, amb claus pròpies. Mira API de les apps anteriors.

Si no funciona

Símptoma. 401 a cada crida. Causa. La clau és incorrecta o s’ha esborrat. Solució. Crea una clau nova.

Símptoma. 403 en una ruta. Causa. L’àmbit de la clau no cobreix aquesta ruta. Solució. Mira l’àmbit de la ruta a Settings > API.

Símptoma. 404 a cada crida. Causa. Falta la URL base. Solució. Posa-la abans de /api/v1. Mira URL base.

Per a experts

Afegeix una ruta

Les rutes viuen al routes.go de cada mòdul. Cadascuna es registra amb el seu mètode, ruta i permís, així que totes tenen una comprovació de permís.

openapi.json surt de les rutes. TestOpenAPIGenerated falla quan no coincideixen, així que actualitza’l al mateix canvi. Una instantània de la taula de rutes també falla quan s’afegeix, s’elimina o es mou una ruta sense actualitzar la instantània.

Un cop publicats, les rutes i els noms dels camps es mantenen. Afegeix camps, no els reanomenis mai. Després d’un canvi, executa go run ./app/backend/tools/apidoc per reescriure Rutes de l’API.

Crides al servidor de metadades

HolyArrs obté noms, imatges i identificadors del servidor de metadades d’HolyArrs. Per apuntar una instal·lació a un altre servidor, fes servir HOLYARRS_METADATA_URL. El codi del servidor no és en aquest repositori.

Registre. A la primera consulta, la instal·lació crida POST /v1/installations sense cos. La resposta és 201 amb {"schema_version":1,"token":"hai_..."}. L’app desa el token xifrat i envia Authorization: Bearer <token> a cada consulta. Es registra una sola vegada. Després d’un 401 no es torna a registrar, així que una instal·lació revocada continua revocada. Si se supera el límit per hora per grup d’adreces, la resposta és 429 registration_limit amb Retry-After.

Consulta (totes GET)	Ruta
Cerca	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
Pel·lícula	/v1/movies/tmdb/{id}
Sèrie	/v1/shows/{tmdb or tvmaze}/{id}
Temporada	/v1/shows/tmdb/{id}/seasons/{n} (la temporada 0 són els especials)
Música	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

Els paràmetres desconeguts o repetits es rebutgen. Els identificadors d’un proveïdor no es fan servir mai per a un altre.

Una bona resposta té schema_version, source, source_id, fetched_at, expires_at, completeness, stale i data. Tracta l’HTML dels resums com a text pla.

Estat	Vol dir
400	Consulta incorrecta, no ho tornis a provar
401	Token incorrecte o revocat, no ho tornis a provar
404	No existeix aquest registre
429	Massa crides, espera el temps de Retry-After
503	Ocupat, espera i torna-ho a provar una vegada

Relacionat

• Rutes de l’API
• API de les apps anteriors
• Variables d’entorn