Bot API ドキュメント

認証

ダッシュボードの Bot API ページでトークンを作成し、Authorization ヘッダーで送信します: Authorization: Bearer <token>。トークンは1つのサーバーに属し、そのサーバーのみ読み取れます。表示は一度きりで、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 は既定でオフです。ウェブページが訪問者のブラウザーから呼び出す必要がある場合は、トークンに許可するウェブサイトを1つ設定します。他のオリジンからのリクエストは拒否されます。ウェブページ内のものはすべて訪問者に見えます。

トークン、プラン、上限

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 を含みます。判断にはコードを使い、メッセージの文面は使わないでください。