機器人 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。請依據代碼判斷，不要依據訊息文字。