Sonarr REST API完全参考API Key认证与自动化集成的终极教程【免费下载链接】SonarrSmart PVR for newsgroup and bittorrent users.项目地址: https://gitcode.com/GitHub_Trending/so/SonarrSonarr是一款面向新闻组Newsgroup和 BitTorrent 用户的智能 PVR自动录像工具能自动搜索、下载、整理你的剧集。本文是 Sonarr REST API 的完整参考教程从获取 API Key、三种认证方式到常用端点与自动化集成场景帮你快速上手用接口玩转 Sonarr。为什么你需要 Sonarr REST APISonarr 的 Web 界面适合日常操作但当你想 把新剧集上架推送到手机或 Home Assistant 用脚本自动触发媒体库扫描、重新扫描硬链接 与自己的自动化系统Webhook、n8n、Tasker 等对接手动点击就远远不够了。Sonarr 内置了一套标准的REST API返回 JSON 数据使用API Key认证几行curl就能完成大部分自动化任务。先了解API 版本与入口Sonarr 的 API 统一挂载在/api路径下。访问该地址可以查看当前版本信息curl http://localhost:8989/api当前主版本为v5旧版v3已标记为弃用建议所有新集成一律使用 v5对应实现见 ApiInfoController.cs。完整的接口契约OpenAPI 规范可以在源码中直接查看是编写自动化脚本时最有价值的参考资料Sonarr.Api.V5/openapi.json —— v5 完整 API 定义Sonarr.Api.V3/openapi.json —— v3 旧版定义三步拿到 API Key 并正确认证1️⃣ 在哪找到 API Key有两个地方位置说明设置 → 常规GeneralWeb 界面中直接查看字段定义见 GeneralSettingsResource.csconfig.xml 配置文件配置项ApiKey见 AuthOptions.cs 小技巧API Key 页面旁通常有重新生成按钮。如果怀疑 Key 泄露重新生成旧 Key 会立即失效。2️⃣ 三种认证方式任选其一Sonarr 的认证处理器 ApiKeyAuthenticationHandler.cs 按以下优先级解析密钥方式用法适用场景请求头X-Api-Key推荐curl -H X-Api-Key: 你的密钥 http://localhost:8989/api/series脚本、程序集成查询参数apikeycurl http://localhost:8989/api/series?apikey你的密钥浏览器、简单调试标准 Bearer 头curl -H Authorization: Bearer 你的密钥 ...兼容通用 HTTP 客户端注册认证方案的配置见 AuthenticationBuilderExtensions.cs。3️⃣ 第一次请求验证连通性curl -H X-Api-Key: 你的密钥 http://localhost:8989/api/system/status返回一段包含版本、数据库、启动状态的 JSON说明认证已生效 ✅常用 REST API 端点速查表端点方法用途/api/seriesGET获取所有剧集列表/api/series/{id}GET / PATCH查看 / 更新单部剧集如监控状态、质量/api/episodeFilesGET已下载并整理好的剧集文件/api/queueGET / DELETE当前下载队列可删除排队任务/api/calendarGET日历接下来要播出的剧集带start/end时间参数/api/commandPOST触发命令媒体库扫描、硬链接扫描、搜索等/api/commands/{id}GET查询命令执行进度/api/healthGET系统健康检查排障第一步/api/historyGET历史记录导入、重命名、删除等事件/api/system/tasksGET定时任务列表与运行时间 命令触发示例POST 触发一次媒体库扫描curl -X POST -H X-Api-Key: 你的密钥 \ -H Content-Type: application/json \ -d {name: RescanSeries} \ http://localhost:8989/api/command所有可用命令名可在 CommandNames 中快速确认。五个最值得落地的自动化集成场景场景一新剧集自动通知最热门每 5 分钟轮询/api/calendar?startnow把新增条目推送到 Telegram / ntfy / 邮件。这是 Sonarr REST API 最经典的组合。场景二下载完成事件驱动轮询/api/history中最新的Imported事件触发 NAS 通知、播放列表更新等。场景三定时库维护用 cron 每天调用POST /api/command触发Scan、Reshard等命令替代手动点击重新扫描。场景四Home Assistant / 智能家居联动Sonarr 状态接入仪表盘当前排队下载数/api/queue长度、系统健康/api/health、最近导入的剧集/api/history。场景五批量管理剧集通过GET /api/seriesPATCH /api/series/{id}批量调整监控选项、质量配置适合统一管理上百部剧的场景。常见错误排查401 / 403 / 404 一次看懂状态码含义常见原因与对策401 Unauthorized认证失败Key 错误、未携带 Key、Key 被重新生成见 ApiKeyAuthenticationHandler.cs 中HandleChallengeAsync返回 401403 Forbidden权限不足通常出现在请求了受限的 UI 相关端点404 Not Found端点不存在URL 拼写错误或使用了弃用的 v3 路径排障三步骤先访问/api确认 API 本身存活再访问/api/health查看 Sonarr 自检结果最后核对 openapi.json 中端点的确切路径与方法GET vs POST。API Key 安全实践清单 ❌ 不要把 Key 写进公开可见的脚本仓库或 URL 日志✅ 优先使用X-Api-Key请求头避免 Key 出现在 URL查询参数会进访问日志✅ 公网暴露时务必开启 Sonarr 的 UI 认证并考虑反向代理 防火墙只放通信任 IP✅ 怀疑泄露时立即在常规设置中重新生成 Key。总结Sonarr REST API 核心要点要点结论入口http://主机:8989/api当前版本 v5认证API KeyX-Api-Key头 /apikey参数 /Bearer头Key 来源设置 → 常规或config.xml最强功能POST /api/command触发任意后台任务参考文档源码内 openapi.json 即权威文档掌握 API Key 认证 这张端点速查表你就能用不到 10 行脚本把 Sonarr 变成自己自动化体系的一部分。动手试试吧 【免费下载链接】SonarrSmart PVR for newsgroup and bittorrent users.项目地址: https://gitcode.com/GitHub_Trending/so/Sonarr创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考