HolyArrs API

Web 应用用的是 /api/v1 下的 JSON API，你自己的脚本也可以调用同一套 API。

发出第一次调用

1. 打开 Settings > API > API keys（设置 > API > API 密钥），创建一个密钥，只给它需要的权限范围。马上复制，因为它只显示一次。
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 密钥、密码和两步验证、登录设置、恢复
control	功能模块开关、环节、关联应用、重启和关闭
all	read、write 和 admin。不含 control

给监控工具只开 health_read，别的都不给。

找一条路由

Settings > API 会显示基础地址、权限范围、调用示例，以及每条路由和它对应的权限范围与权限。登录后可以在 /api/v1/openapi.json 拿到 OpenAPI 文件。API 路由列出了全部路由。

以旧应用的方式和 HolyArrs 通信

Seerr、Overseerr、Bazarr 这类应用不用这套 API。它们把 HolyArrs 当成 Sonarr 和 Radarr 来通信，用的是另外一套密钥。见旧应用 API。

如果不成功

现象。 每次调用都返回 401。 原因。 密钥不对，或者已被删除。 解决办法。 创建一个新密钥。

现象。 某一条路由返回 403。 原因。 密钥的权限范围不包含这条路由。 解决办法。 在 Settings > API 查这条路由的权限范围。

现象。 每次调用都返回 404。 原因。 少了 URL 基础路径。 解决办法。 把它加在 /api/v1 前面。见 URL 基础路径。

进阶

添加一条路由

路由写在每个模块的 routes.go 里。每条路由注册时都带着方法、路径和权限，所以每条路由都有权限检查。

openapi.json 由路由生成。两者不一致时 TestOpenAPIGenerated 会失败，所以要在同一次改动里更新它。添加、删除或移动路由却没有更新路由表快照时，快照检查也会失败。

一旦发布，路径和字段名就不再变。可以加字段，不能改名。改完后运行 go run ./app/backend/tools/apidoc，重新生成 API 路由。

元数据服务器的调用

HolyArrs 从 HolyArrs 元数据服务器获取名称、图片和 id。用 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}

未知的参数或重复的参数会被拒绝。一个数据提供方的 id 不会用到另一个提供方上。

正常的返回包含 schema_version、source、source_id、fetched_at、expires_at、completeness、stale 和 data。简介里的 HTML 要当作纯文本处理。

状态码	含义
400	查询有误，不要重试
401	令牌无效或已被吊销，不要重试
404	没有这条记录
429	调用太多，等 Retry-After 指定的时间
503	服务器忙，等一会儿再重试一次

相关页面

• API 路由
• 旧应用 API
• 环境变量