REST API 入门：用 X-API-Key 查状态与触发重启

API 与 GUI 是同一个服务

管理界面所在的 8384 端口同时提供 REST API——浏览器里渲染界面用的就是这套接口。API 的鉴权靠 API Key：管理界面 Settings → General 里能看到，也可以在 config.xml 的 <gui><apikey> 元素里找到。命令行还有 --gui-apikey 参数与环境变量 STGUIAPIKEY 可覆盖它。

调用时把 Key 放在请求头：

X-API-Key: 你的API密钥

常用端点速览

官方 API 文档把端点按资源分组，系统类的一组包括：

GET  /rest/system/status     运行状态（版本、运行时长、资源占用等）
GET  /rest/system/version    版本信息
GET  /rest/system/connections 各设备连接状态
GET  /rest/system/browse     浏览服务器目录
POST /rest/system/restart    触发重启
POST /rest/system/shutdown   触发关机

其余分组覆盖文件夹、设备、数据库等资源的查看与修改，结构与之类似。

一个最小调用示例

curl -H "X-API-Key: 你的API密钥" localhost:8384/rest/system/version

返回 JSON。把地址换成远程机器、配合 SSH 隧道即可远程查询（隧道方法见[远程访问管理界面(../07-网络与连通/05-remote-gui.md)）。

典型用途

• 监控脚本：定时拉 system/connections，发现设备长期走中继就发通知；
• 自动化：备份完成后触发任务、按计划暂停/恢复文件夹；
• 第三方面板：社区有多个基于 API 的状态面板与移动端伴侣应用。

安全边界

API 权限等同 GUI：能读写配置与触发动作。保持 8384 只绑定 localhost（或隧道访问），Key 不要写进公开的脚本仓库——官方对「服务化必须设 GUI 密码」的警告同样覆盖 API（见[配置文件与密钥都在哪(01-config-files.md)）。