La API de HolyArrs

Llama desde tus propios scripts a la misma API JSON que usa la app web, bajo /api/v1.

Haz tu primera llamada

1. Abre Settings > API > API keys (Ajustes > API > Claves de API) y crea una clave solo con los alcances que necesite. Cópiala en ese momento, porque se muestra una sola vez.
2. Envíala en la cabecera X-Api-Key en cada llamada. Nunca la pongas en la dirección.
3. Llama a la dirección base http://your-server:6262/api/v1. Con una URL base /holyarrs, llama a 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"

Deberías recibir JSON. Los errores son {"error": "plain words"} con un estado HTTP. Los secretos llegan ocultos.

Opciones

Elige un alcance

Alcance	Permite
health_read	Solo el feed de salud, para herramientas de monitorización
read	Las rutas de lectura, incluido el feed de salud
write	Cambios, salvo las rutas de administración y los controles
admin	Personas, invitaciones, límites de solicitudes, claves de API, contraseñas y verificación en dos pasos, ajustes de inicio de sesión, restauración
control	Interruptores de las Partes, etapas, apps vinculadas, reiniciar y apagar
all	read, write y admin. No incluye control

A una herramienta de monitorización dale health_read y nada más.

Encuentra una ruta

Settings > API muestra la dirección base, los alcances, llamadas de ejemplo y todas las rutas con su alcance y su permiso. El archivo OpenAPI está en /api/v1/openapi.json cuando tienes la sesión iniciada. Rutas de la API enumera todas las rutas.

Habla con HolyArrs como una app anterior

Seerr, Overseerr, Bazarr y apps parecidas no usan esta API. Hablan con HolyArrs como si fuera Sonarr y Radarr, con claves propias. Consulta API de apps anteriores.

Si no funciona

Síntoma. 401 en todas las llamadas. Causa. La clave es incorrecta o se eliminó. Solución. Crea una clave nueva.

Síntoma. 403 en una ruta. Causa. El alcance de la clave no cubre esa ruta. Solución. Revisa el alcance de la ruta en Settings > API.

Síntoma. 404 en todas las llamadas. Causa. Falta la URL base. Solución. Ponla antes de /api/v1. Consulta URL base.

Para expertos

Añadir una ruta

Las rutas están en el routes.go de cada módulo. Cada una se registra con su método, su ruta y su permiso, así que todas las rutas tienen una comprobación de permiso.

openapi.json se genera a partir de las rutas. TestOpenAPIGenerated falla cuando dejan de coincidir, así que actualízalo en el mismo cambio. Una instantánea de la tabla de rutas también falla cuando una ruta se añade, se quita o se mueve sin actualizar la instantánea.

Una vez publicados, las rutas y los nombres de los campos se quedan. Añade campos, nunca los renombres. Después de un cambio, ejecuta go run ./app/backend/tools/apidoc para reescribir Rutas de la API.

Llamadas al servidor de metadatos

HolyArrs obtiene nombres, imágenes e ids del servidor de metadatos de HolyArrs. Apunta una instalación a otro servidor con HOLYARRS_METADATA_URL. El código del servidor no está en este repositorio.

Registro. En su primera consulta, una instalación llama a POST /v1/installations sin cuerpo. La respuesta es 201 con {"schema_version":1,"token":"hai_..."}. La app guarda el token cifrado y envía Authorization: Bearer <token> en cada consulta. Se registra una sola vez. Después de un 401 no vuelve a registrarse, así que una instalación revocada sigue revocada. Si se supera el límite por hora de cada grupo de direcciones, la respuesta es 429 registration_limit con Retry-After.

Consulta (todas GET)	Ruta
Búsqueda	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
Película	/v1/movies/tmdb/{id}
Serie	/v1/shows/{tmdb or tvmaze}/{id}
Temporada	/v1/shows/tmdb/{id}/seasons/{n} (la temporada 0 son los especiales)
Música	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

Los parámetros desconocidos o repetidos se rechazan. Los ids de un proveedor nunca se usan para otro.

Una respuesta correcta tiene schema_version, source, source_id, fetched_at, expires_at, completeness, stale y data. Trata el HTML de los resúmenes como texto sin formato.

Estado	Significa
400	Consulta incorrecta, no reintentes
401	Token incorrecto o revocado, no reintentes
404	No existe ese registro
429	Demasiadas llamadas, espera lo que indique Retry-After
503	Ocupado, espera y reintenta una vez

Relacionado

• Rutas de la API
• API de apps anteriores
• Variables de entorno