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_..."}. Приложението пази token-а криптиран и го праща като 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	Лош или отнет token, не опитвай отново
404	Няма такъв запис
429	Твърде много извиквания, изчакай Retry-After
503	Заето, изчакай и опитай още веднъж

Свързано

• API маршрути
• API за по-старите приложения
• Променливи на средата