Documentation de l'API du Bot

Authentification

Crée un jeton sur la page API du Bot de ton tableau de bord et envoie-le dans l'en-tête Authorization : Authorization: Bearer <token>. Un jeton appartient à un serveur et ne lit que ce serveur. Il n'est affiché qu'une fois ; DayZ Hub ne garde que son empreinte.

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

URL de base: https://dayzhub.net/api/v1/bot

Endpoints

Chaque réponse est du JSON dans la même enveloppe. Les listes sont paginées avec limit (1 à 100) et le curseur de page.nextCursor.

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

Scopes

Chaque jeton ne détient que les scopes que tu lui as donnés. Tous sont en lecture seule ; rien ne peut être modifié via cette API.

Confidentialité des membres

Les membres n'apparaissent que là où la fonctionnalité les montre déjà publiquement, sous forme d'identifiant Discord. Un membre opposé au traitement de ses données est toujours montré comme anonyme, comme ci-dessous. Noms, messages, tickets et réponses de formulaires ne font jamais partie de l'API.

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

Limites

Les limites suivent le forfait du serveur. Premium 1 : 2 jetons actifs, 60 requêtes par minute par jeton. Premium 2 : 5 jetons, 120 par minute. Premium 3 : 10 jetons, 300 par minute. Un essai gratuit ou un serveur sponsorisé compte comme Premium 1. Chaque adresse IP peut faire 300 requêtes par minute. Au-delà tu reçois 429 avec l'en-tête Retry-After. Un forfait qui baisse ne révoque aucun jeton : ceux que tu as continuent de fonctionner, seuls les nouveaux sont bloqués jusqu'à ce que tu repasses sous la limite. Le serveur doit avoir un forfait payant ou un essai actif.

Cache

Les réponses portent un ETag et un court cache privé. Envoie If-None-Match pour obtenir 304 quand rien n'a changé. Interroger toutes les 30 à 60 secondes suffit largement.

Navigateurs et CORS

Appelle l'API depuis ton serveur. CORS est désactivé par défaut. Si une page web doit l'appeler depuis le navigateur d'un visiteur, définis un site autorisé sur le jeton ; les requêtes de toute autre origine sont refusées. Tout ce qui est dans une page web est visible des visiteurs.

Ton jeton, ton forfait et tes limites

GET /me ne vérifie pas le forfait. En plus du jeton lui-même, il renvoie plan (premium1, premium2, premium3 ou none), limits (tokens et perMinute de ce forfait) et tokensUsed (jetons actifs du serveur). rateLimitPerMin est le débit dont ce jeton dispose en ce moment.

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

Identifiants de requête

Chaque réponse porte l'en-tête X-Request-Id. Si tu envoies ton propre X-Request-Id (jusqu'à 64 lettres, chiffres et . _ : -), il est conservé, sinon il est généré. Les erreurs le répètent sous requestId. Indique-le quand tu contactes le support.

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

Erreurs

Les erreurs sont du JSON avec ok: false, un code stable dans code (error contient la même valeur), un court message et le requestId. Décide d'après le code, jamais d'après le texte du message.