HolyArrs API

設定

從你自己的腳本呼叫 Web App 使用的同一組 JSON API，路徑在 /api/v1 底下。

發出第一次呼叫

開啟 Settings > API > API keys（設定 > API > API 金鑰），建立一把金鑰，只給它需要的範圍。現在就複製，因為金鑰只會顯示一次。
每次呼叫都把金鑰放在 X-Api-Key header 裡。不要放在位址中。
呼叫基本位址 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 狀態碼。機密資料會以遮蔽後的形式回傳。

選項

選擇範圍

Scope	允許的操作
`health_read`	只有健康狀態 feed，給監控工具用
`read`	讀取類的路由，包含健康狀態 feed
`write`	各種變更，管理員路由與控制除外
`admin`	使用者、邀請、請求額度、API 金鑰、密碼與兩步驟驗證、登入設定、還原
`control`	功能區塊開關、階段、已連結的 App、重新啟動與關機
`all`	`read`、`write` 和 `admin`。不含 `control`

監控工具只給 health_read，其他都不要給。

找到路由

Settings > API 會顯示基本位址、範圍、呼叫範例，以及每一條路由的範圍和權限。登入後，OpenAPI 檔案位於 /api/v1/openapi.json。所有路由的清單在 API 路由。

以舊的 App 身分與 HolyArrs 溝通

Seerr、Overseerr、Bazarr 和類似的 App 不使用這組 API。它們會把 HolyArrs 當成 Sonarr 和 Radarr 來溝通，並使用各自專用的金鑰。請看舊 App API。

如果沒有成功

症狀。 每次呼叫都回傳 401。 原因。 金鑰錯誤或已被刪除。 解決方式。 建立新的金鑰。

症狀。 某一條路由回傳 403。 原因。 金鑰的範圍沒有涵蓋那條路由。 解決方式。 到 Settings > API 查看那條路由的範圍。

症狀。 每次呼叫都回傳 404。 原因。 少了 URL base。 解決方式。 把它放在 /api/v1 前面。請看 URL base。

給進階使用者

新增路由

路由都在各模組的 routes.go 裡。每一條路由註冊時都帶有方法、路徑和權限，所以每條路由都有權限檢查。

openapi.json 由路由產生。兩者不一致時 TestOpenAPIGenerated 會失敗，所以要在同一次變更裡一起更新。如果新增、移除或搬動了路由卻沒有更新快照，路由表快照也會失敗。

發布之後，路徑和欄位名稱就不再變動。只新增欄位，不重新命名。變更之後，執行 go run ./app/backend/tools/apidoc 來重寫 API 路由。

metadata 伺服器呼叫

HolyArrs 從 HolyArrs metadata 伺服器取得名稱、圖片和 id。用 HOLYARRS_METADATA_URL 可以讓安裝指向另一台伺服器。伺服器的程式碼不在這個 repo 裡。

註冊。 第一次查詢時，安裝會不帶內容呼叫 POST /v1/installations。回應是 201，內容為 {"schema_version":1,"token":"hai_..."}。App 會把 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}`

未知或重複的參數會被拒絕。某個提供者的 id 絕不會拿去給另一個提供者用。

正常的回應含有 schema_version、source、source_id、fetched_at、expires_at、completeness、stale 和 data。摘要裡的 HTML 要當成純文字處理。

狀態碼	意思
400	查詢有誤，不要重試
401	token 錯誤或已被撤銷，不要重試
404	沒有這筆記錄
429	呼叫太多次，等 `Retry-After` 指定的時間
503	忙碌中，等一下再重試一次