HolyArrs API

Web アプリが使っているのと同じ JSON API を、/api/v1 以下で自作のスクリプトから呼び出せます。

最初の呼び出し

1. Settings > API > API keys(設定 > API > API キー)を開き、必要なスコープだけを付けたキーを作ります。キーは 1 回しか表示されないので、その場でコピーします。
2. すべての呼び出しで、キーを X-Api-Key ヘッダーに入れて送ります。アドレスには決して入れません。
3. ベースアドレス http://your-server:6262/api/v1 を呼び出します。URL ベースが /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 キー、パスワードと 2 要素認証、サインインの設定、復元
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 が返る。 原因。 キーが間違っているか、削除されています。 対処。 新しいキーを作ります。

症状。 1 つのルートだけ 403 が返る。 原因。 キーのスコープがそのルートを含んでいません。 対処。 Settings > API でそのルートのスコープを確認します。

症状。 すべての呼び出しで 404 が返る。 原因。 URL ベースが抜けています。 対処。 /api/v1 の前に URL ベースを入れます。URL ベース を参照してください。

上級者向け

ルートを追加する

ルートは各モジュールの routes.go にあります。どのルートもメソッド、パス、権限とあわせて登録するので、すべてのルートに権限チェックがかかります。

openapi.json はルートから生成されます。ずれがあると TestOpenAPIGenerated が失敗するので、同じ変更の中で更新してください。ルート表のスナップショットもあり、スナップショットを更新せずにルートを追加、削除、移動すると失敗します。

一度リリースしたら、パスとフィールド名は変えません。フィールドは追加するだけで、名前の変更はしません。変更したあとは go run ./app/backend/tools/apidoc を実行して API ルート を書き直します。

メタデータサーバーの呼び出し

HolyArrs は、名前、画像、ID を HolyArrs のメタデータサーバーから取得します。HOLYARRS_METADATA_URL を使うと、別のサーバーを参照させられます。サーバーのコードはこのリポジトリにはありません。

登録。 インストールした HolyArrs は、最初の検索のときに本文なしで POST /v1/installations を呼び出します。応答は 201 で、内容は {"schema_version":1,"token":"hai_..."} です。アプリはトークンを暗号化して保存し、検索のたびに Authorization: Bearer <token> を送ります。登録は 1 回だけです。401 が返ったあとは再登録しないので、取り消されたインストールは取り消されたままになります。アドレスグループごとの 1 時間あたりの上限を超えると、応答は 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}

知らないパラメーターや重複したパラメーターは拒否されます。あるプロバイダーの ID を別のプロバイダーに使うことはありません。

正常な応答には schema_version、source、source_id、fetched_at、expires_at、completeness、stale、data が含まれます。あらすじに含まれる HTML は、ただのテキストとして扱ってください。

ステータス	意味
400	クエリが不正。再試行しない
401	トークンが不正、または取り消し済み。再試行しない
404	該当するレコードがない
429	呼び出しが多すぎる。Retry-After の時間だけ待つ
503	混雑中。待ってから 1 回だけ再試行する

関連ページ

• API ルート
• 旧アプリ API
• 環境変数