Bot-API

Was du bauen kannst

Mit der Bot-API können deine eigene Website oder deine Tools aktuelle Fakten über deinen Discord-Server lesen. Sie liest nur. Nichts, was du damit baust, kann deinen Server verändern oder deine Mitglieder anrühren. Hier sind ein paar Ideen, die man an einem Nachmittag umsetzen kann.

• Ein Ranglisten-WidgetZeige die 10 besten Überlebenden nach Level auf der Website deiner Community.
• Ein Gewinnspiel-CountdownZeige das laufende Gewinnspiel, den Preis und das Ende auf deiner Startseite.
• TicketzahlenZeige, wie viele Tickets offen sind und wie schnell dein Team antwortet, für ein Team-Dashboard oder ein Banner wie „Wir antworten in etwa 10 Minuten“.
• Ein Status-BadgeZeige, ob dein Spielserver online ist und wie viele Spieler darauf sind.
• Eine Produktliste des ShopsListe die Produkte deines Spenden-Shops mit Preisen auf deiner eigenen Seite auf und verlinke direkt zur Kasse.

Schritt für Schritt: Token erstellen

Ein Token ist ein langes geheimes Passwort, mit dem eine Website oder ein Tool deinen Server lesen darf. Du erstellst ihn in deinem Dashboard.

1. 01

   Seite Bot-API öffnen

   Melde dich auf dayzhub.net an, öffne dein Dashboard, wähle deinen Server und klicke im Seitenmenü unter Verwaltung auf Bot-API. Nur Personen mit der Berechtigung Server verwalten sehen sie. Mitglieder mit Teamzugriff nicht.

2. 02

   Name vergeben

   Gib einen kurzen Namen ein, der dir sagt, wofür er gedacht ist, zum Beispiel „Website-Rangliste“. Verwende pro Website oder Tool einen eigenen Token.

3. 03

   Wähle, was er lesen darf

   Hake die Kästchen für die Daten an, die du brauchst, etwa Gewinnspiele oder die Level-Rangliste. Weniger Kästchen sind sicherer. Du kannst später jederzeit einen weiteren Token erstellen.

4. 04

   Erlaubte Website (nur manchmal)

   Lass das Feld leer, außer eine Webseite ruft die API direkt im Browser deiner Besucher auf. Dann gib die Adresse deiner Seite genau so ein, wie https://deineseite.com, ohne Pfad am Ende.

5. 05

   Auf Token erstellen klicken und ihn kopieren

   Ein Fenster mit deinem Token erscheint, der mit dhba_ beginnt. Klicke auf Kopieren und füge ihn sofort an einem sicheren Ort ein. Er wird nur einmal angezeigt. Wenn du ihn verlierst, erstellst du einen neuen.

6. 06

   Halte ihn geheim

   Behandle den Token wie ein Passwort. Poste ihn nicht in Discord, lege ihn nicht in ein öffentliches GitHub-Projekt und füge ihn nicht in eine Webseite ein, die Besucher lesen können. Bewahre ihn auf deinem eigenen Server oder in einem Passwortmanager auf.

Deine erste Anfrage

Prüfen wir, ob dein Token funktioniert. Du brauchst zwei Dinge: den Token, den du gerade kopiert hast, und deine Server-ID (aktiviere in Discord in den Einstellungen den Entwicklermodus, klicke dann mit der rechten Maustaste auf deinen Server und wähle Server-ID kopieren). Der erste Aufruf unten braucht nur den Token.

Ersetze in jedem Beispiel dhba_YOUR_TOKEN durch deinen echten Token. Jedes Beispiel sendet den Token in einem Header namens Authorization. Ihn in die Webadresse zu schreiben funktioniert nicht.

Windows PowerShell (use curl.exe with the .exe, plain curl means something else in PowerShell)

curl.exe -H "Authorization: Bearer dhba_YOUR_TOKEN" https://dayzhub.net/api/v1/bot/me

curl (macOS, Linux and most hosting)

curl -H "Authorization: Bearer dhba_YOUR_TOKEN" https://dayzhub.net/api/v1/bot/me

JavaScript on your own server (Node 18 or newer). Keep the token in an environment variable.

const res = await fetch("https://dayzhub.net/api/v1/bot/guilds/YOUR_SERVER_ID/giveaways?status=active", {
  headers: { Authorization: "Bearer " + process.env.DAYZHUB_BOT_API_TOKEN }
});
const { ok, data } = await res.json();
console.log(data);

JavaScript in a visitor's browser (needs the Allowed website setting on the token, and shows the token to everyone, so use a token with the fewest boxes ticked)

fetch("https://dayzhub.net/api/v1/bot/guilds/YOUR_SERVER_ID/leaderboard/levels?limit=10", {
  headers: { Authorization: "Bearer dhba_YOUR_TOKEN" }
}).then(r => r.json()).then(j => console.log(j.data));

Was zurückkommt

Jede Antwort ist JSON. Erfolgreiche Antworten enthalten "ok": true und deine Daten. Listen kommen mit einem Teil "page": Wenn "hasMore" true ist, sende den Wert von "nextCursor" als ?cursor= zurück, um die nächste Seite zu holen. Datumsangaben sind in UTC.

GET /me: who the token belongs to

{
  "ok": true,
  "data": {
    "guildId": "123456789012345678",
    "name": "Website leaderboard",
    "prefix": "dhba_aB3dE",
    "scopes": ["leveling:read", "giveaways:read"],
    "allowedOrigin": null,
    "rateLimitPerMin": 60,
    "createdAt": "2026-10-01T12:00:00.000Z",
    "plan": "premium1",
    "limits": { "tokens": 2, "perMinute": 60 },
    "tokensUsed": 1
  }
}

GET /guilds/ID/leaderboard/levels?limit=2

{
  "ok": true,
  "data": [
    { "rank": 1, "member": { "id": "111111111111111111", "anonymous": false }, "xp": 18450, "level": 27 },
    { "rank": 2, "member": { "id": null, "anonymous": true }, "xp": 17020, "level": 26 }
  ],
  "page": { "limit": 2, "hasMore": true, "nextCursor": "eyJpZCI6IjY..." }
}

GET /guilds/ID/giveaways?status=active

{
  "ok": true,
  "data": [{
    "id": "6650f0c2a1b2c3d4e5f60718",
    "prize": "Premium VIP for 30 days",
    "status": "active",
    "type": "reaction",
    "winnerCount": 1,
    "entryCount": 86,
    "endsAt": "2026-10-08T18:00:00.000Z",
    "requirements": { "role": false, "verified": true, "minInvites": 0 },
    "host": { "id": "111111111111111111", "anonymous": false },
    "winners": []
  }],
  "page": { "limit": 25, "hasMore": false, "nextCursor": null }
}

GET /guilds/ID/tickets/summary

{
  "ok": true,
  "data": {
    "open": 4,
    "closed": 212,
    "total": 216,
    "last30Days": { "created": 38, "closed": 41, "averageRating": 4.7, "ratingCount": 29, "averageFirstResponseMinutes": 9.5 },
    "byCategory": [ { "category": "Support", "open": 3, "closed": 150 } ]
  }
}

GET /guilds/ID/shop/products

{
  "ok": true,
  "shop": { "name": "Survivor HQ Shop", "description": "Support the server", "slug": "survivor-hq", "url": "https://dayzhub.net/shop/survivor-hq" },
  "data": [{
    "id": "6650f0c2a1b2c3d4e5f60999", "name": "VIP Role", "slug": "vip-role", "description": "Priority queue and a gold name",
    "price": 9.99, "compareAtPrice": null, "currency": "EUR", "type": "subscription", "interval": "monthly",
    "thumbnailUrl": null, "featured": true, "inStock": true, "url": "https://dayzhub.net/shop/survivor-hq/vip-role"
  }],
  "page": { "limit": 25, "hasMore": false, "nextCursor": null }
}

GET /guilds/ID/server-status

{
  "ok": true,
  "data": {
    "listed": true,
    "servers": [{ "name": "Survivor HQ", "slug": "survivor-hq", "url": "https://dayzhub.net/s/survivor-hq", "online": true, "players": 42, "maxPlayers": 60, "address": "game.yourserver.gg:2302", "lastChangeAt": "2026-10-01T09:30:00.000Z" }]
  }
}

When something is wrong, for example a mixed-up server ID (HTTP 403)

{ "ok": false, "error": "guild_mismatch", "code": "guild_mismatch", "message": "This token belongs to another server", "requestId": "3f2b8c1e-5a7d-4e0b-9c64-1d2e3f4a5b6c" }

Die vollständige Liste der Endpunkte und aller Felder findest du in der maschinenlesbaren Beschreibung unter /api/v1/bot/openapi.json. Jede Antwort trägt den Header X-Request-Id, und Fehler wiederholen ihn als requestId. Nenne ihn, wenn du den Support kontaktierst.

Limits, Pläne und Datenschutz

• Nur lesendEs gibt keine Schaltflächen, die etwas ändern. Es werden nur GET-Anfragen beantwortet.
• PläneDein Server braucht einen bezahlten Plan oder eine aktive kostenlose Testphase. Gewinnspieldaten brauchen Premium 2. Die Shop-Liste braucht echten bezahlten Zugang, denn die kostenlose Testphase enthält den Spenden-Shop nicht.
• Wie viele Token du haben kannstPremium 1 enthält 2 aktive Token, Premium 2 enthält 5 und Premium 3 enthält 10. Eine kostenlose Testphase oder ein gesponserter Server zählt als Premium 1. Widerrufe die, die du nicht mehr brauchst, um Platz zu schaffen. Sinkt dein Plan, funktionieren die Token, die du schon hast, weiter. Du kannst nur keine neuen erstellen, bis du unter dem Limit bist.
• GeschwindigkeitslimitsJeder Token darf bei Premium 1 60 Anfragen pro Minute stellen, bei Premium 2 120 und bei Premium 3 300, und eine Internetadresse 300 pro Minute. Darüber gibt es eine 429-Antwort mit einem Retry-After-Header, der sagt, wie viele Sekunden du warten sollst.
• Rücksichtsvoll abfragenDie Antworten enthalten einen ETag. Sende ihn in einem If-None-Match-Header zurück, und wenn sich nichts geändert hat, bekommst du eine winzige 304-Antwort statt aller Daten. Alle 30 bis 60 Sekunden zu fragen reicht völlig, und die meisten Widgets können seltener fragen.
• Was nie geteilt wirdTicket-Protokolle und Nachrichten, Bewerbungen und ihre Antworten, Zahlungen und Bestellungen, E-Mail-Adressen, Namen und Avatare sowie die Personen, die an einem Gewinnspiel teilgenommen haben. Du bekommst immer nur Zahlen, dazu numerische Discord-IDs dort, wo die Funktion Personen in Discord ohnehin öffentlich zeigt, etwa bei einem Gewinnspiel-Host oder der Level-Rangliste.
• Mitglieder, die widersprochen habenWer /privacy optout genutzt hat, erscheint immer als anonym (eine id von null). Rang und Zahlen zählen trotzdem mit, sodass die Summen stimmen.

Fehlerbehebung

Token widerrufen und austauschen

Tu das sofort, wenn ein Token versehentlich weitergegeben oder öffentlich gepostet wurde oder wenn jemand, der ihn kannte, dein Team verlassen hat.

1. 01

   Zuerst den neuen Token erstellen

   Erstelle auf der Seite Bot-API einen Ersatz mit denselben Einstellungen und kopiere ihn.

2. 02

   Website oder Tool umstellen

   Trage den neuen Token überall ein, wo der alte verwendet wurde, und prüfe, ob alles noch funktioniert.

3. 03

   Den alten widerrufen

   Klicke in der Liste deiner Token beim alten auf Widerrufen und bestätige. Er funktioniert sofort nicht mehr, und alles, was ihn noch nutzt, bekommt eine 401. Erstellen und Widerrufen werden in das Audit-Log deines Servers geschrieben, nie der Token selbst.

Fragen, die Leute stellen