L'API di HolyArrs

Chiama dai tuoi script la stessa API JSON che usa l’app web, sotto /api/v1.

Fai la tua prima chiamata

1. Apri Settings > API > API keys (impostazioni, API, chiavi API) e crea una chiave con solo gli ambiti che ti servono. Copiala subito, perché viene mostrata una volta sola.
2. Mandala nell’header X-Api-Key a ogni chiamata. Non metterla mai nell’indirizzo.
3. Chiama l’indirizzo base http://your-server:6262/api/v1. Con un URL base /holyarrs, chiama 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"

Dovresti ricevere un JSON. Gli errori sono {"error": "plain words"} con uno stato HTTP. I segreti tornano mascherati.

Scelte

Scegli un ambito

Ambito	Permette
health_read	Solo il feed di salute, per gli strumenti di monitoraggio
read	Le route di lettura, feed di salute compreso
write	Le modifiche, tranne le route e i controlli di amministrazione
admin	Persone, inviti, limiti di richiesta, chiavi API, password e autenticazione a due fattori, impostazioni di accesso, ripristino
control	Interruttori delle parti, fasi, app collegate, riavvio e arresto
all	read, write e admin. Non control

A uno strumento di monitoraggio dai health_read e nient’altro.

Trova una route

Settings > API mostra l’indirizzo base, gli ambiti, esempi di chiamate e ogni route con il suo ambito e il suo permesso. Il file OpenAPI si trova in /api/v1/openapi.json quando hai effettuato l’accesso. Route dell’API elenca tutte le route.

Parla con HolyArrs come un’app precedente

Seerr, Overseerr, Bazarr e app simili non usano questa API. Parlano con HolyArrs come se fosse Sonarr e Radarr, con chiavi proprie. Vedi API delle app precedenti.

Se non funziona

Sintomo. 401 a ogni chiamata. Causa. La chiave è sbagliata o è stata eliminata. Soluzione. Crea una nuova chiave.

Sintomo. 403 su una route. Causa. L’ambito della chiave non copre quella route. Soluzione. Controlla l’ambito della route in Settings > API.

Sintomo. 404 a ogni chiamata. Causa. Manca l’URL base. Soluzione. Mettilo prima di /api/v1. Vedi URL base.

Per esperti

Aggiungere una route

Le route stanno nel file routes.go di ogni modulo. Ognuna è registrata con il suo metodo, il suo percorso e il suo permesso, quindi ogni route ha un controllo dei permessi.

openapi.json nasce dalle route. TestOpenAPIGenerated fallisce quando i due non coincidono più, quindi aggiornalo nella stessa modifica. Anche lo snapshot della tabella delle route fallisce quando una route viene aggiunta, rimossa o spostata senza aggiornare lo snapshot.

Dopo il rilascio, percorsi e nomi dei campi restano uguali. Aggiungi campi, non rinominarli mai. Dopo una modifica, esegui go run ./app/backend/tools/apidoc per riscrivere Route dell’API.

Chiamate al server di metadati

HolyArrs prende nomi, immagini e id dal server di metadati di HolyArrs. Per puntare un’installazione a un altro server usa HOLYARRS_METADATA_URL. Il codice del server non è in questo repo.

Registrazione. Alla prima ricerca, un’installazione chiama POST /v1/installations senza corpo. La risposta è 201 con {"schema_version":1,"token":"hai_..."}. L’app salva il token cifrato e manda Authorization: Bearer <token> a ogni ricerca. Si registra una volta sola. Dopo un 401 non si registra di nuovo, quindi un’installazione revocata resta revocata. Se superi il limite orario per gruppo di indirizzi, la risposta è 429 registration_limit con Retry-After.

Ricerca (tutte GET)	Route
Ricerca	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
Film	/v1/movies/tmdb/{id}
Serie	/v1/shows/{tmdb or tvmaze}/{id}
Stagione	/v1/shows/tmdb/{id}/seasons/{n} (la stagione 0 è quella degli speciali)
Musica	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

I parametri sconosciuti o ripetuti vengono rifiutati. Gli id di un provider non si usano mai per un altro.

Una buona risposta contiene schema_version, source, source_id, fetched_at, expires_at, completeness, stale e data. Tratta l’HTML nei riassunti come testo semplice.

Stato	Significa
400	Richiesta errata, non riprovare
401	Token errato o revocato, non riprovare
404	Nessun record di questo tipo
429	Troppe chiamate, aspetta Retry-After
503	Occupato, aspetta e riprova una volta

Correlati

• Route dell’API
• API delle app precedenti
• Variabili d’ambiente