Dokumentace API bota

Ověření

Vytvoř token na stránce API bota ve svém panelu a pošli ho v hlavičce Authorization: Authorization: Bearer <token>. Token patří jednomu serveru a čte jen ten server. Zobrazí se jednou; DayZ Hub uchovává jen jeho otisk.

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

Základní URL: https://dayzhub.net/api/v1/bot

Koncové body

Každá odpověď je JSON ve stejné obálce. Seznamy se stránkují pomocí limit (1 až 100) a kurzoru z page.nextCursor.

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

Rozsahy

Každý token má jen rozsahy, které mu dáš. Všechny jsou jen pro čtení; přes toto API nelze nic změnit.

Soukromí členů

Členové se objevují jen tam, kde je funkce už veřejně ukazuje, jako ID Discordu. Člen, který vznesl námitku proti zpracování dat, je vždy zobrazen anonymně, jak je vidět níže. Jména, zprávy, tickety a odpovědi z formulářů nejsou nikdy součástí API.

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

Limity

Limity se řídí tarifem serveru. Premium 1: aktivních tokenů 2, požadavků za minutu na token 60. Premium 2: tokenů 5, 120 za minutu. Premium 3: tokenů 10, 300 za minutu. Zkušební doba zdarma nebo sponzorovaný server se počítá jako Premium 1. Každá IP adresa může provést 300 požadavků za minutu. Při překročení dostaneš 429 s hlavičkou Retry-After. Snížení tarifu žádný token nezruší: tokeny, které máš, dál fungují, jen nové jsou blokované, dokud nejsi pod limitem. Server potřebuje placený tarif nebo aktivní zkušební dobu.

Mezipaměť

Odpovědi nesou ETag a krátkou soukromou mezipaměť. Pošli If-None-Match, abys dostal 304, když se nic nezměnilo. Dotazování každých 30 až 60 sekund bohatě stačí.

Prohlížeče a CORS

Volej API z vlastního serveru. CORS je ve výchozím stavu vypnut. Pokud ho musí webová stránka volat z prohlížeče návštěvníka, nastav na tokenu jeden povolený web; požadavky z jakéhokoli jiného původu jsou odmítnuty. Vše na webové stránce vidí návštěvníci.

Tvůj token, tarif a limity

GET /me nekontroluje tarif. Kromě samotného tokenu vrací plan (premium1, premium2, premium3 nebo none), limits (tokens a perMinute tohoto tarifu) a tokensUsed (aktivní tokeny serveru). rateLimitPerMin je rychlost, kterou tento token má právě teď.

{ "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 požadavků

Každá odpověď nese hlavičku X-Request-Id. Pokud pošleš vlastní X-Request-Id (až 64 písmen, číslic a znaků . _ : -), zůstane zachováno, jinak se vygeneruje. Chyby ho opakují jako requestId. Uveď ho, když kontaktuješ podporu.

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

Chyby

Chyby jsou JSON s ok: false, stabilním kódem v code (error obsahuje stejnou hodnotu), krátkou zprávou a requestId. Rozhoduj podle kódu, nikdy podle textu zprávy.