HTTP API

HTTP / 控制 API（2.6.x）

现行接口文档，适用于稳定版 2.6.0 PEAK（v2.6.0_PEAK）与预发布 2.6.1 RIDGE（v2.6.1_RIDGE）。源码在 main。

2.6.1 新增的内测端点（默认关闭）见 Beta-Features。

历史 2.5.x（control_token + 旧扁平路径）见 Old-HTTP-API。

鉴权（双轨）

通道	凭据	配置
`GET /get_sl_data`、`GET /plugins/adapted` 等数据口	`verify_token`	`config.yml`
`/control/*`、控制 WS、语音 `:8082`	API Key	`apikey.config`（与 `config.yml` 同目录）

数据口（verify_token）

推荐请求头：

Authorization: Bearer <verify_token>
X-SLDataAPI-Token: <verify_token>
X-SLDataAPI-Verify-Token: <verify_token>

?token= 仍兼容但已弃用（会入访问日志），后续版本将移除。

出厂 / 弱 verify_token（空、默认 your_secret_token、或不满足强度：长度 ≥8 且同时含大写/小写/数字/特殊符号）→ fail-closed：数据口拒绝；若控制面也未启用则不绑定 HTTP 端口。详见 Security-Model。

控制 / 语音（API Key）

Authorization: Bearer <api_key>
X-SLDataAPI-Key: <api_key>

不再接受： control_token、X-Control-Token、控制面 ?key= / ?token= → 401。
config.yml 里若仍写 control_token，启动仅警告后忽略，不作为鉴权。

HTTP	含义
`401`	Key 缺失 / 错误 / 锁定
`403`	Key 有效但被拒绝（ACL、远程执行 `sldataapi`、无权限路径等）
`404`	`control_enabled: false`、传输模式互斥、未知路径、内测开关未开
`405`	非 POST
`413`	body > 64KB
`501`	已知占位（inventory / dummies）

响应体统一：{ "success", "message", "data" }。

Key 生命周期

sldataapi apikey create <id> <duty|admin> [note]
sldataapi apikey list
sldataapi apikey revoke <id>

仅服务器本地控制台可执行；经 /control/console/command 或控制 WS 一律拒绝。
落盘只存 SHA-256 指纹；明文写入一次性文件（约 5 分钟自动删），命令输出只回路径。
审计 control_log 的 actor 为 Key 的 id。
模板 duty / admin 影响默认 ACL（duty 默认不可全量读审计 body）。详见 Configuration。

只读数据

curl -s "http://<host>:8081/get_sl_data" \
  -H "Authorization: Bearer YOUR_VERIFY_TOKEN"

# 兼容（已弃用）
curl -s "http://<host>:8081/get_sl_data?token=YOUR_VERIFY_TOKEN"

快照字段说明可参考 Old-HTTP-API 中「只读数据」一节（字段大体连续；2.6 另含 adapted_plugins 等扩展）。

适配插件发现

其他 LabAPI 插件可经 PluginEndpointRegistry 登记自身能力（插件侧用法见 Development-Guide · 适配插件集成）。两个只读入口，鉴权同数据口（verify_token），仅 GET（其他方法 405）：

GET /plugins/adapted——全量列表（与 get_sl_data.adapted_plugins 同结构）：

{"success":true,"adapted_plugins":[
  {"id":"dntof.sample_adapted","name":"Adapted Plugin Sample","version":"1.1.0",
   "capabilities":["sample.hello"],"routes":["hello"],
   "status":{"ok":true,"message":"sample online","bumps":0}}
]}

字段	说明
`id`	插件 id（`^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$`，建议反向域名）
`name` / `version`	展示名 / 版本
`capabilities`	能力标签（≤32）
`routes`	只读子路径名（≤16）
`actions`	仅 2.6.1 且 `beta_adapted_plugin_actions: true` 时出现：写 / 动作名，见 Beta-Features
`status`	插件状态回调返回的 JSON（≤4KB；超限为 `{"error":"status_too_large"}`，回调异常为 `{"error":"status_failed"}`，无回调为 `null`）

列表取自主线程快照（随 push_interval_seconds 刷新），status 可能略有滞后。内置条目 dntof.sl_player、dntof.omega_warhead 为 SLDataAPI 自带的探测包装。

GET /plugins/<plugin_id>/<route>——调用插件登记的只读子路径：

项	说明
路径	恰好两段；`route` 形如 `^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$`；含 `..` → 400
执行	主线程，超时 3s（超时 → 504）
响应	插件返回的 JSON 原样返回；返回 `null` → `{}`；非 JSON 文本 → `{"ok":true,"data":"<文本>"}`；>64KB → 413
错误	未注册 → 404 `plugin not registered`；无此路由 → 404 `route not found`；处理器异常 → 500

curl -s "http://<host>:8081/plugins/dntof.sample_adapted/hello" \
  -H "Authorization: Bearer YOUR_VERIFY_TOKEN"

控制端点（POST + JSON）

control_transport: ws 时 HTTP /control/* → 404 + transport_mismatch。

curl -s -X POST "http://<host>:8081/control/map/layout" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

路径一览

分组	路径	备注
Player	`/control/player/data` · `role` · `effects` · `inventory`	`inventory` → 501
Moderation	`/control/moderation/kick` · `ban` · `mute` · `msg` · `ban_list` · `ban/add` · `ban/revoke`
Admin	`/control/admin/teleport` · `state`
Broadcast	`/control/broadcast` · `/control/staffchat`	已实现；admin 默认开，duty 默认关
Round	`/control/round` · `round/warhead` · `round/wave`
Map	`/control/map/facility` · `layout` · `export` · `seed`
Other	`/control/cassie` · `/control/dummies`	`dummies` → 501
扩展	`/control/console/command` · `plugins` · `plugins/slplayer` · `files/*` · `logs` · `reports` · `audit/list`	`console` / `plugins` / `files` 默认不授予（含 admin）
内测（2.6.1）	`/control/adapted/<plugin_id>/<action>` · `files/stat` · `files/read_chunk` · `files/write_chunk`	默认关闭 + 默认拒绝，见 Beta-Features

默认 ACL 要点

admin 模板（及 all_control_true）按端点目录展开，但目录里以下条目为 false，admin 也不会自动获得：

键	覆盖
`/control/console/`	`console/command`（等同本机控制台）
`/control/plugins`、`/control/plugins/`	插件列表 / 启停、`plugins/slplayer`
`/control/files/`	全部文件端点
`/control/adapted/`	适配插件动作（2.6.1 内测）
`/control/player/inventory`	占位（501）

需要时对单把 Key 用 endpoints_override 显式放开（写法见 Beta-Features「权限（ACL）」一节与 Configuration）。ACL 为最长前缀匹配：以 / 结尾的键同时覆盖不带斜杠的同名路径，因此放开插件管理时请把 /control/plugins 与 /control/plugins/ 一起设为 true（只设前者会被后者的 false 盖住）。

插件管理 `/control/plugins`

body	作用	ACL 读写
`{}`	列表	读
`{"action":"stage","name":"<插件名>","enabled":true}`	暂存启停（不写文件；不能禁用 SLDataAPI 自身）	写
`{"action":"clear"}`	清空暂存	写
`{"action":"apply"}`	写入全部暂存：LabAPI 插件写各自的 `LabAPI/configs/<端口>/<插件名>/properties.yml`，重启服务器后生效；EXILED 插件立即重载	写
`{"action":"reload"}`	热重载其他插件的配置文件（不含 SLDataAPI 自身，不重载 DLL、不应用启停）	写

带任何非空 action（包括 "list"）都按写计入 ACL 与审计；只想列表请发空对象 {}。

列表响应 data：

{"count":2,"plugins":[
  {"name":"SLDataAPI","author":"DNT_OF","version":"2.6.1","prefix":"","priority":"Medium",
   "enabled":true,"self":true,"staged":null,"source":"labapi"}
]}

enabled 读自配置文件（LabAPI properties.yml / EXILED is_enabled），不是运行时状态；staged 为暂存的目标值（无则 null）；source 为 labapi 或 exiled。

文件 `/control/files/list|read|write`

需配置 file_root（为空 → 404）。路径相对 file_root，防线见 Security-Model「文件端点」一节。

端点	body	`data`
`files/list`	`{"path":""}`（空 = 根）	`{"path","count","entries":[{"name","type":"dir\|file","size","modified","protected"}]}`
`files/read`	`{"path":"a.yml"}`	`{"path","size","modified","content"}`（文件 ≤1MB）
`files/write`	`{"path":"a.yml","content":"..."}`	`{"path","bytes"}`（内容 ≤512K 字符；HTTP 请求体另受 64KB 限制）

大文件请用 2.6.1 的分块端点（Beta-Features）。

全服广播

curl -s -X POST "http://<host>:8081/control/broadcast" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"服务器维护通知","duration_seconds":10,"clear_previous":true}'

字段	说明
`message`	必填，≤500
`duration_seconds`	可选，默认 5，上限 60
`clear_previous`	可选 bool

管理聊天（RA AdminChat）

curl -s -X POST "http://<host>:8081/control/staffchat" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"值班备注","is_silent":false}'

字段	说明
`message`	必填，≤500
`is_silent`	可选 bool

自 2.5 升级：路径对照

2.5	2.6.x
`/control/command`	`/control/console/command`
`/control/player/kick` 等	`/control/moderation/...`
`/control/player/teleport`	`/control/admin/teleport`
`/control/player/effect`	`/control/player/effects`
`/control/player/state`	`/control/admin/state`
`/control/map`（混用）	`map/facility`（写）+ `layout` / `export` / `seed`（读）
`/control/warhead` / `wave`	`/control/round/warhead` / `wave`
`/control/ban_*`	`/control/moderation/ban_*`
`/control/slplayer`	`/control/plugins/slplayer`

无兼容别名；旧 path → 404 或 403。

语音口（8082）

鉴权同控制面（Bearer / X-SLDataAPI-Key）。不要在 URL 带 key。

路径	说明
`GET /ws`（升级 WS）	语音流
`GET /status`	说话状态

帧格式见 Voice-Forwarding。可选 WebDAV 定稿 zip（仅 https://）见 Configuration。

迁移清单

设置强 verify_token；数据口改用请求头，少用 ?token=
控制 / 语音 / 控制 WS：改用 API Key 头；删除 X-Control-Token / control_token
按上表改 path；broadcast / staffchat 已可用
按需要创建多把 Key（duty / admin）
丢失 Key：本地 revoke + create（无法找回明文）

SLDataAPI Wiki

Home
接口
- HTTP-API
- WS-Control-Protocol
- Beta-Features（2.6.1 RIDGE 内测）
- Old-HTTP-API（2.5.x 历史）
语音
- Voice-Forwarding
- Voice-Recording
运维
开发
- Architecture
- Development-Guide

Releases · Issues

Navigation Menu

Uh oh!

HTTP API

HTTP / 控制 API（2.6.x）

鉴权（双轨）

数据口（verify_token）

控制 / 语音（API Key）

Key 生命周期

只读数据

适配插件发现

控制端点（POST + JSON）

路径一览

默认 ACL 要点

插件管理 `/control/plugins`

文件 `/control/files/list|read|write`

全服广播

管理聊天（RA AdminChat）

自 2.5 升级：路径对照

语音口（8082）

迁移清单

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

Uh oh!

HTTP API

HTTP / 控制 API（2.6.x）

鉴权（双轨）

数据口（verify_token）

控制 / 语音（API Key）

Key 生命周期

只读数据

适配插件发现

控制端点（POST + JSON）

路径一览

默认 ACL 要点

插件管理 /control/plugins

文件 /control/files/list|read|write

全服广播

管理聊天（RA AdminChat）

自 2.5 升级：路径对照

语音口（8082）

迁移清单

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

插件管理 `/control/plugins`

文件 `/control/files/list|read|write`