API HolyArrs

Вызывайте из своих скриптов тот же JSON API, которым пользуется веб-приложение. Он находится по пути /api/v1.

Первый вызов

1. Откройте Settings > API > API keys (Настройки > API > ключи API) и создайте ключ только с теми областями доступа, которые ему нужны. Скопируйте его сразу: он показывается один раз.
2. Передавайте его в заголовке X-Api-Key при каждом вызове. Никогда не вставляйте его в адрес.
3. Обращайтесь по базовому адресу http://your-server:6262/api/v1. Если задан URL base /holyarrs, обращайтесь по адресу 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"

В ответ вы получите JSON. Ошибки приходят в виде {"error": "plain words"} с кодом состояния HTTP. Секреты возвращаются скрытыми.

Варианты выбора

Выберите область доступа

Область доступа	Что разрешает
health_read	Только ленту исправности, для средств мониторинга
read	Маршруты чтения, включая ленту исправности
write	Изменения, кроме маршрутов администрирования и управления
admin	Люди, приглашения, лимиты запросов, ключи API, пароли и двухфакторная защита, настройки входа, восстановление
control	Переключатели Частей, этапы, связанные приложения, перезапуск и выключение
all	read, write и admin. Без control

Средству мониторинга дайте health_read и больше ничего.

Найдите маршрут

На странице Settings > API показаны базовый адрес, области доступа, примеры вызовов и все маршруты с их областью доступа и правами. Файл OpenAPI доступен по адресу /api/v1/openapi.json, когда вы вошли. Все маршруты перечислены на странице Маршруты API.

Обращайтесь к HolyArrs как к прежнему приложению

Seerr, Overseerr, Bazarr и похожие приложения этим API не пользуются. Они обращаются к HolyArrs так, будто это Sonarr и Radarr, и у них свои ключи. См. API прежних приложений.

Если не работает

Признак проблемы. 401 на каждый вызов. Причина. Ключ неверный или удалён. Решение. Создайте новый ключ.

Признак проблемы. 403 на одном маршруте. Причина. Область доступа ключа не охватывает этот маршрут. Решение. Проверьте область доступа маршрута на странице Settings > API.

Признак проблемы. 404 на каждый вызов. Причина. Не указан URL base. Решение. Поставьте его перед /api/v1. См. URL base.

Для опытных

Добавить маршрут

Маршруты лежат в файле routes.go каждого модуля. Каждый маршрут регистрируется с методом, путём и правами, поэтому у каждого маршрута есть проверка прав.

openapi.json строится по маршрутам. Тест TestOpenAPIGenerated падает, когда они расходятся, поэтому обновляйте файл в том же изменении. Снимок таблицы маршрутов тоже не проходит, если маршрут добавлен, удалён или перемещён, а снимок не обновлён.

После выхода версии пути и имена полей не меняются. Добавляйте поля, но никогда не переименовывайте их. После изменения выполните go run ./app/backend/tools/apidoc, чтобы перезаписать страницу Маршруты API.

Вызовы сервера метаданных

Названия, изображения и идентификаторы HolyArrs получает от сервера метаданных HolyArrs. Направить установку на другой сервер можно переменной HOLYARRS_METADATA_URL. Кода сервера в этом репозитории нет.

Регистрация. При первом поиске данных установка вызывает POST /v1/installations без тела. Ответ — 201 с {"schema_version":1,"token":"hai_..."}. Приложение хранит токен в зашифрованном виде и отправляет Authorization: Bearer <token> при каждом поиске данных. Регистрация проходит один раз. После 401 приложение не регистрируется заново, поэтому отозванная установка остаётся отозванной. Если превышен часовой лимит на группу адресов, ответ — 429 registration_limit с Retry-After.

Поиск данных (везде GET)	Маршрут
Поиск	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
Фильм	/v1/movies/tmdb/{id}
Сериал	/v1/shows/{tmdb or tvmaze}/{id}
Сезон	/v1/shows/tmdb/{id}/seasons/{n} (сезон 0 — спецвыпуски)
Музыка	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

Неизвестные и повторяющиеся параметры отклоняются. Идентификаторы одного поставщика никогда не используются для другого.

В хорошем ответе есть schema_version, source, source_id, fetched_at, expires_at, completeness, stale и data. HTML в описаниях считайте обычным текстом.

Код	Что значит
400	Неверный запрос, не повторяйте
401	Неверный или отозванный токен, не повторяйте
404	Такой записи нет
429	Слишком много вызовов, подождите время из Retry-After
503	Сервер занят, подождите и повторите один раз

См. также

• Маршруты API
• API прежних приложений
• Переменные окружения