Dokumentation der Bot-API

Authentifizierung

Erstelle einen Token auf der Seite Bot-API deines Dashboards und sende ihn im Header Authorization: Authorization: Bearer <token>. Ein Token gehört zu einem Server und kann nur diesen lesen. Er wird einmal angezeigt; DayZ Hub speichert nur seinen Fingerabdruck.

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

Basis-URL: https://dayzhub.net/api/v1/bot

Endpunkte

Jede Antwort ist JSON im selben Umschlag. Listen sind seitenweise abrufbar mit limit (1 bis 100) und dem Cursor aus page.nextCursor.

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

Scopes

Jeder Token hat nur die Scopes, die du ihm gegeben hast. Alle sind nur lesend; über diese API lässt sich nichts ändern.

Datenschutz der Mitglieder

Mitglieder erscheinen nur dort, wo die Funktion sie bereits öffentlich zeigt, als Discord-ID. Ein Mitglied, das der Datenverarbeitung widersprochen hat, wird immer anonym gezeigt, wie unten. Namen, Nachrichten, Tickets und Formularantworten sind nie Teil der API.

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

Limits

Die Limits folgen dem Plan des Servers. Premium 1: 2 aktive Token, 60 Anfragen pro Minute und Token. Premium 2: 5 Token, 120 pro Minute. Premium 3: 10 Token, 300 pro Minute. Eine kostenlose Testphase oder ein gesponserter Server zählt als Premium 1. Jede IP-Adresse darf 300 Anfragen pro Minute stellen. Darüber gibt es 429 mit dem Header Retry-After. Ein niedrigerer Plan widerruft keinen Token: Die vorhandenen Token funktionieren weiter, nur neue sind gesperrt, bis du unter dem Limit bist. Der Server braucht einen bezahlten Plan oder eine aktive Testphase.

Caching

Antworten enthalten einen ETag und einen kurzen privaten Cache. Sende If-None-Match, um 304 zu erhalten, wenn sich nichts geändert hat. Abfragen alle 30 bis 60 Sekunden reichen völlig.

Browser und CORS

Rufe die API von deinem Server aus auf. CORS ist standardmäßig aus. Muss eine Webseite sie im Browser eines Besuchers aufrufen, setze eine erlaubte Website am Token; Anfragen von jeder anderen Origin werden abgelehnt. Alles in einer Webseite ist für Besucher sichtbar.

Dein Token, Plan und Limits

GET /me braucht keine Plan-Prüfung. Neben dem Token selbst liefert es plan (premium1, premium2, premium3 oder none), limits (tokens und perMinute dieses Plans) und tokensUsed (aktive Token des Servers). rateLimitPerMin ist die Rate, die dieser Token gerade hat.

{ "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 } }

Request-IDs

Jede Antwort trägt den Header X-Request-Id. Sendest du eine eigene X-Request-Id (bis zu 64 Buchstaben, Ziffern und . _ : -), bleibt sie erhalten, sonst wird eine erzeugt. Fehler wiederholen sie als requestId. Nenne sie, wenn du den Support kontaktierst.

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" }

Fehler

Fehler sind JSON mit ok: false, einem stabilen Code in code (error enthält denselben Wert), einer kurzen Meldung und der requestId. Entscheide nach dem Code, nie nach dem Meldungstext.