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 для попередніх застосунків
• Змінні середовища