机器人 API 文档

身份验证

在控制面板的机器人 API 页面创建令牌，并通过 Authorization 请求头发送：Authorization: Bearer <token>。一个令牌属于一个服务器，只能读取该服务器。令牌只显示一次；DayZ Hub 只保存其指纹。

curl -H "Authorization: Bearer dhba_..." \
  https://dayzhub.net/api/v1/bot/guilds/<guildId>

基础 URL: https://dayzhub.net/api/v1/bot

端点

每个响应都是相同封装的 JSON。列表通过 limit（1 到 100）和 page.nextCursor 中的游标分页。

{ "ok": true, "data": [ ... ], "page": { "limit": 25, "hasMore": true, "nextCursor": "eyJpZCI6Ij..." } }

权限范围

每个令牌只拥有你授予的权限范围。全部为只读；无法通过此 API 更改任何内容。

成员隐私

成员只会出现在该功能已公开显示他们的地方，以 Discord ID 形式出现。选择退出数据处理的成员始终显示为匿名，如下所示。名称、消息、工单和表单回答绝不属于 API 的一部分。

{ "id": null, "anonymous": true }

限制

限制取决于服务器的套餐。Premium 1：2 个有效令牌，每个令牌每分钟 60 个请求。Premium 2：5 个令牌，每分钟 120 个。Premium 3：10 个令牌，每分钟 300 个。免费试用或受赞助的服务器按 Premium 1 计算。每个 IP 地址每分钟最多 300 个请求。超出限制将返回带有 Retry-After 头的 429。套餐降级不会撤销任何令牌：你已有的令牌继续可用，只是在降到上限以下之前不能创建新令牌。服务器需要付费套餐或有效试用。

缓存

响应带有 ETag 和较短的私有缓存。发送 If-None-Match，在没有变化时会返回 304。每 30 到 60 秒轮询一次已经足够。

浏览器与 CORS

请从你的服务器调用 API。CORS 默认关闭。如果网页必须在访客浏览器中调用它，请在令牌上设置一个允许的网站；来自任何其他来源的请求都会被拒绝。网页中的所有内容访客都能看到。

你的令牌、套餐和限制

GET /me 不检查套餐。除令牌本身外，它还返回 plan（premium1、premium2、premium3 或 none）、limits（该套餐的 tokens 和 perMinute）以及 tokensUsed（服务器的有效令牌数）。rateLimitPerMin 是此令牌当前的速率。

{ "ok": true, "data": { "guildId": "123456789012345678", "name": "Website", "prefix": "dhba_aB3dE", "scopes": ["guild:read"],
  "allowedOrigin": null, "rateLimitPerMin": 120, "createdAt": "2026-10-01T12:00:00.000Z",
  "plan": "premium2", "limits": { "tokens": 5, "perMinute": 120 }, "tokensUsed": 2 } }

请求 ID

每个响应都带有 X-Request-Id 头。如果你发送自己的 X-Request-Id（最多 64 个字母、数字以及 . _ : -），会被保留，否则会自动生成。错误响应中会以 requestId 重复它。联系支持时请提供它。

X-Request-Id: 3f2b8c1e-5a7d-4e0b-9c64-1d2e3f4a5b6c

{ "ok": false, "error": "rate_limited", "code": "rate_limited", "message": "Too many requests", "requestId": "3f2b8c1e-5a7d-4e0b-9c64-1d2e3f4a5b6c" }

错误

错误以 JSON 返回，包含 ok: false、code 中的稳定错误代码（error 的值相同）、简短消息和 requestId。请根据代码判断，不要依据消息文字。