Документация API бота

Аутентификация

Создайте токен на странице API бота в панели и отправляйте его в заголовке Authorization: Authorization: Bearer <token>. Токен принадлежит одному серверу и читает только его. Он показывается один раз; DayZ Hub хранит только его отпечаток.

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

Базовый URL: https://dayzhub.net/api/v1/bot

Эндпоинты

Каждый ответ — JSON в одной и той же обёртке. Списки разбиты на страницы через limit (от 1 до 100) и курсор из page.nextCursor.

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

Области

У каждого токена только те области, которые вы ему дали. Все они только для чтения; через этот API ничего изменить нельзя.

Конфиденциальность участников

Участники появляются только там, где функция уже показывает их публично, как идентификатор Discord. Участник, отказавшийся от обработки данных, всегда показывается анонимно, как ниже. Имена, сообщения, тикеты и ответы форм никогда не входят в API.

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

Лимиты

Лимиты зависят от тарифа сервера. Premium 1: активных токенов 2, запросов в минуту на токен 60. Premium 2: токенов 5, 120 в минуту. Premium 3: токенов 10, 300 в минуту. Бесплатный пробный период и спонсируемый сервер считаются как Premium 1. Каждый IP-адрес может делать 300 запросов в минуту. При превышении вы получите 429 с заголовком Retry-After. Понижение тарифа не отзывает ни один токен: имеющиеся продолжают работать, блокируется только создание новых, пока вы не окажетесь ниже лимита. Серверу нужен платный тариф или активный пробный период.

Кэширование

Ответы содержат ETag и короткий приватный кэш. Отправьте If-None-Match, чтобы получить 304, если ничего не изменилось. Опроса раз в 30–60 секунд более чем достаточно.

Браузеры и CORS

Вызывайте API со своего сервера. CORS по умолчанию выключен. Если веб-странице нужно вызывать его из браузера посетителя, укажите у токена один разрешённый сайт; запросы с любого другого источника отклоняются. Всё, что есть на веб-странице, видно посетителям.

Ваш токен, тариф и лимиты

GET /me не проверяет тариф. Помимо самого токена он возвращает plan (premium1, premium2, premium3 или none), limits (tokens и perMinute этого тарифа) и tokensUsed (активные токены сервера). rateLimitPerMin — скорость, которая есть у этого токена сейчас.

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

Идентификаторы запросов

Каждый ответ содержит заголовок X-Request-Id. Если вы отправите свой X-Request-Id (до 64 букв, цифр и символов . _ : -), он сохранится, иначе он будет создан. В ошибках он повторяется как requestId. Назовите его, когда обращаетесь в поддержку.

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

Ошибки

Ошибки — это JSON с ok: false, стабильным кодом в code (error содержит то же значение), коротким сообщением и requestId. Ориентируйтесь на код, а не на текст сообщения.