Bot API

What you can build

The Bot API lets your own website or tools read live facts about your Discord server. It only reads. Nothing you build with it can change your server or touch your members. Here are some ideas that people set up in an afternoon.

• A leaderboard widgetShow your top 10 survivors by level on your community website.
• A giveaway countdownPut the running giveaway, its prize and its end time on your homepage.
• Ticket countsShow how many tickets are open and how fast your team answers, for a staff dashboard or a "we reply in about 10 minutes" banner.
• A status badgeDisplay whether your game server is online and how many players are on it.
• A shop product listList your Donation Shop products with prices on your own site and link straight to checkout.

Step by step: create your token

A token is a long secret password that lets one website or tool read your server. You make it in your dashboard.

1. 01

   Open the Bot API page

   Log in at dayzhub.net, open your dashboard, pick your server, and choose Bot API in the Management section of the side menu. Only people with the Manage Server permission can see it. Team Access members cannot.

2. 02

   Name it

   Type a short name that tells you what it is for, for example "Website leaderboard". Use one token per website or tool.

3. 03

   Choose what it may read

   Tick the boxes for the data you need, such as giveaways or the level leaderboard. Fewer boxes is safer. You can always make another token later.

4. 04

   Allowed website (only sometimes)

   Leave this empty unless a web page in your visitors' browsers will call the API directly. In that case type your site address exactly, like https://yoursite.com, with no path at the end.

5. 05

   Press Create token and copy it

   A box appears with your token, which starts with dhba_. Press Copy and paste it somewhere safe right away. It is shown only once. If you lose it, you make a new one.

6. 06

   Keep it secret

   Treat the token like a password. Do not post it in Discord, do not put it in a public GitHub project, and do not paste it into a web page that visitors can read. Keep it on your own server or in a password manager.

Your first request

Let us check that your token works. You need two things: the token you just copied, and your server ID (in Discord, turn on Developer Mode in your settings, then right-click your server and choose Copy Server ID). The first call below needs only the token.

Replace dhba_YOUR_TOKEN with your real token in every example. Each one sends the token in a header called Authorization. Putting it in the web address does not work.

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));

What comes back

Every answer is JSON. Successful answers have "ok": true and your data. Lists come with a "page" part: when "hasMore" is true, pass the "nextCursor" value back as ?cursor= to get the next page. Dates are 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" }

The full list of endpoints and every field is in the machine-readable description at /api/v1/bot/openapi.json. Every answer carries an X-Request-Id header, and errors repeat it as requestId. Quote it when you contact support.

Limits, plans and privacy

• Read onlyThere are no buttons that change anything. Only GET requests are answered.
• PlansYour server needs a paid plan or an active free trial. Giveaway data needs Premium 2. The shop list needs real paid access, because the free trial does not include the Donation Shop.
• How many tokens you can havePremium 1 includes 2 active tokens, Premium 2 includes 5 and Premium 3 includes 10. A free trial or a sponsored server counts as Premium 1. Revoke the ones you no longer use to free a place. If your plan goes down, the tokens you already have keep working. You just cannot create new ones until you are under the limit.
• Speed limitsEach token may make 60 requests per minute on Premium 1, 120 on Premium 2 and 300 on Premium 3, and one internet address 300 per minute. Past that you get a 429 answer with a Retry-After header telling you how many seconds to wait.
• Polling kindlyAnswers include an ETag. Send it back in an If-None-Match header and, when nothing changed, you get a tiny 304 answer instead of the full data. Asking every 30 to 60 seconds is plenty, and most widgets can ask less often.
• What is never sharedTicket transcripts and messages, applications and their answers, payments and orders, e-mail addresses, names and avatars, and the people who entered a giveaway. You only ever get counts, plus numeric Discord IDs where the feature already shows people publicly in Discord, such as a giveaway host or the level leaderboard.
• Members who opted outAnyone who used /privacy optout always appears as anonymous (an id of null). Their rank and numbers still count, so totals add up.

Troubleshooting

Revoke and rotate a token

Do this at once if a token was shared by mistake, posted publicly, or a person who knew it has left your team.

1. 01

   Create the new token first

   On the Bot API page create a replacement with the same settings, and copy it.

2. 02

   Switch your website or tool

   Put the new token wherever the old one was used and check that everything still works.

3. 03

   Revoke the old one

   In the list of your tokens, press Revoke on the old one and confirm. It stops working immediately, and anything still using it gets a 401. Creating and revoking are written to your server audit log, never the token itself.

Questions people ask