Справочник API: Модерация

Эндпоинты

Пути указаны относительно https://console.botgg.app/api/v1. Передавайте API-ключ в заголовке Authorization: Bearer botgg_…; ID — строки.

Эндпоинты: Модерация
Эндпоинт	Право	Описание
GET`/guilds/{guildId}/moderation/cases`	`moderation:read`	List moderation cases
GET`/guilds/{guildId}/moderation/cases/{number}`	`moderation:read`	Get a moderation case
POST`/guilds/{guildId}/moderation/users/{userId}/warn`	`moderation:write`	Warn a member
POST`/guilds/{guildId}/moderation/users/{userId}/timeout`	`moderation:write`	Time out a member
POST`/guilds/{guildId}/moderation/users/{userId}/untimeout`	`moderation:write`	Remove a member’s timeout
POST`/guilds/{guildId}/moderation/users/{userId}/kick`	`moderation:write`	Kick a member
POST`/guilds/{guildId}/moderation/users/{userId}/ban`	`moderation:write`	Ban a user
POST`/guilds/{guildId}/moderation/users/{userId}/unban`	`moderation:write`	Unban a user
GET`/guilds/{guildId}/moderation/actions/{actionId}`	`moderation:write`	Get the result of a moderation action

Кроме собственных ошибок (см. ниже), любой эндпоинт может вернуть эти общие:

Ошибки
HTTP	Коды
400	`INVALID_REQUEST`
401	`UNAUTHORIZED`, `INVALID_API_KEY`, `API_KEY_REVOKED`, `API_KEY_EXPIRED`
403	`BROWSER_REQUESTS_NOT_ALLOWED`, `GUILD_MISMATCH`, `INSUFFICIENT_SCOPE`, `GUILD_BLOCKED`
404	`BOT_NOT_IN_GUILD`
429	`RATE_LIMITED`
500	`INTERNAL`

List moderation cases

GET/guilds/{guildId}/moderation/cases

Право: moderation:readЧувствительное

Newest first (deleted cases are left out). Pass before=<nextCursor> for the next page.

На сервере должен быть включён модуль: Модерация

Параметры
Имя	Где	Тип	Обязательное	Описание
`guildId`	путь	`string`	Да	ID вашего сервера · Discord ID (строка)
`action`	query	`string`	Нет	Одно из `warn`, `timeout`, `untimeout`, `kick`, `ban`, `tempban`, `softban`, `unban`, `note`, `purge`
`source`	query	`string`	Нет	Одно из `command`, `automod`, `escalation`, `antiraid`, `antinuke`, `console`, `api`
`userId`	query	`string`	Нет	Only cases against this user Discord ID (строка)
`moderatorId`	query	`string`	Нет	Discord ID (строка)
`active`	query	`string`	Нет	1 = only running warnings / timeouts / tempbans Одно из `1`, `0`, `true`, `false`
`limit`	query	`integer`	Нет	1–100 · По умолчанию `25`
`before`	query	`integer`	Нет	1–999 999 999

Ответ

Поля ответа · 200
Поле	Тип	Обязательное	Описание
`items`	`array of object`	Да
`items[].number`	`integer`	Да
`items[].action`	`string`	Да	Одно из `warn`, `timeout`, `untimeout`, `kick`, `ban`, `tempban`, `softban`, `unban`, `note`, `purge`
`items[].userId`	`string`	Да	The target
`items[].userTag`	`string \| null`	Да
`items[].moderatorId`	`string`	Да
`items[].reason`	`string \| null`	Да
`items[].durationSeconds`	`integer \| null`	Да
`items[].evidence`	`array of string`	Да
`items[].source`	`string`	Да	Одно из `command`, `automod`, `escalation`, `antiraid`, `antinuke`, `console`, `api`
`items[].active`	`boolean`	Да
`items[].expiresAt`	`string \| null`	Да	ISO 8601 date-time
`items[].resolvedAt`	`string \| null`	Да	ISO 8601 date-time
`items[].dmStatus`	`string \| null`	Да	Одно из `sent`, `failed`, `off`
`items[].apiKey`	`object \| null`	Да	Set when the action was made with an API key
`items[].apiKey.id`	`integer \| null`	Да
`items[].apiKey.name`	`string \| null`	Да
`items[].createdAt`	`string \| null`	Да	ISO 8601 date-time
`nextCursor`	`string \| null`	Да

Ответ · 200

{
  "items": [
    {
      "number": 7,
      "action": "warn",
      "userId": "876543210987654321",
      "userTag": "example",
      "moderatorId": "234567890123456789",
      "reason": "Tournament prize",
      "durationSeconds": 3600,
      "evidence": [
        "example"
      ],
      "source": "command",
      "active": true,
      "expiresAt": "2026-10-07T12:00:00.000Z",
      "resolvedAt": "2026-10-07T12:00:00.000Z",
      "dmStatus": "sent",
      "apiKey": {
        "id": 98765,
        "name": "Example"
      },
      "createdAt": "2026-10-07T12:00:00.000Z"
    }
  ],
  "nextCursor": "98700"
}

Примеры

curl

curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/moderation/cases?limit=25" \
  -H "Authorization: Bearer $BOTGG_API_KEY"

JavaScript (fetch)

// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/moderation/cases?limit=25', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);

Python (requests)

import os
import requests

res = requests.get(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/moderation/cases",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
    },
    params={
        "limit": 25,
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

Ошибки

Ошибки
HTTP	Коды
409	`FEATURE_DISABLED`
503	`SERVICE_UNAVAILABLE`

Get a moderation case

GET/guilds/{guildId}/moderation/cases/{number}

Право: moderation:readЧувствительное

With its timeline (created, reason / evidence edits, DM, expired, revoked, escalated).

На сервере должен быть включён модуль: Модерация

Параметры
Имя	Где	Тип	Обязательное	Описание
`guildId`	путь	`string`	Да	ID вашего сервера · Discord ID (строка)
`number`	путь	`string`	Да

Ответ

Поля ответа · 200
Поле	Тип	Обязательное	Описание
`number`	`integer`	Да
`action`	`string`	Да	Одно из `warn`, `timeout`, `untimeout`, `kick`, `ban`, `tempban`, `softban`, `unban`, `note`, `purge`
`userId`	`string`	Да	The target
`userTag`	`string \| null`	Да
`moderatorId`	`string`	Да
`reason`	`string \| null`	Да
`durationSeconds`	`integer \| null`	Да
`evidence`	`array of string`	Да
`source`	`string`	Да	Одно из `command`, `automod`, `escalation`, `antiraid`, `antinuke`, `console`, `api`
`active`	`boolean`	Да
`expiresAt`	`string \| null`	Да	ISO 8601 date-time
`resolvedAt`	`string \| null`	Да	ISO 8601 date-time
`dmStatus`	`string \| null`	Да	Одно из `sent`, `failed`, `off`
`apiKey`	`object \| null`	Да	Set when the action was made with an API key
`apiKey.id`	`integer \| null`	Да
`apiKey.name`	`string \| null`	Да
`createdAt`	`string \| null`	Да	ISO 8601 date-time
`events`	`array of object`	Да
`events[].type`	`string`	Да
`events[].actorId`	`string \| null`	Да
`events[].data`	`any`	Да
`events[].createdAt`	`string \| null`	Да	ISO 8601 date-time

Ответ · 200

{
  "number": 7,
  "action": "warn",
  "userId": "876543210987654321",
  "userTag": "example",
  "moderatorId": "234567890123456789",
  "reason": "Tournament prize",
  "durationSeconds": 3600,
  "evidence": [
    "example"
  ],
  "source": "command",
  "active": true,
  "expiresAt": "2026-10-07T12:00:00.000Z",
  "resolvedAt": "2026-10-07T12:00:00.000Z",
  "dmStatus": "sent",
  "apiKey": {
    "id": 98765,
    "name": "Example"
  },
  "createdAt": "2026-10-07T12:00:00.000Z",
  "events": [
    {
      "type": "example",
      "actorId": "234567890123456789",
      "data": null,
      "createdAt": "2026-10-07T12:00:00.000Z"
    }
  ]
}

Примеры

curl

curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/moderation/cases/234567890123456789" \
  -H "Authorization: Bearer $BOTGG_API_KEY"

JavaScript (fetch)

// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/moderation/cases/234567890123456789', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);

Python (requests)

import os
import requests

res = requests.get(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/moderation/cases/234567890123456789",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

Ошибки

Ошибки
HTTP	Коды
404	`CASE_NOT_FOUND`
409	`FEATURE_DISABLED`
503	`SERVICE_UNAVAILABLE`

Warn a member

POST/guilds/{guildId}/moderation/users/{userId}/warn

Право: moderation:writeЧувствительноеIdempotency-Key

Same as /warn: a warning case (counts toward escalation), DM per the Moderation settings. Acts in the name of the key’s creator, who must still have the matching Discord permission; the target must be below their and the bot’s highest role (never the owner, the bot or the creator). The bot runs it within a few seconds — poll GET …/moderation/actions/{actionId}. At most 10 actions a minute per key. Written to the audit log.

На сервере должен быть включён модуль: Модерация

Параметры
Имя	Где	Тип	Обязательное	Описание
`guildId`	путь	`string`	Да	ID вашего сервера · Discord ID (строка)
`userId`	путь	`string`	Да	Discord ID участника · Discord ID (строка)
`Idempotency-Key`	заголовок	`string`	Нет	Необязательно. Передайте уникальное значение (UUID) и повторяйте его при ретраях — операция выполнится один раз. Как это работает

Тело запроса

Тело запроса
Поле	Тип	Обязательное	Описание
`reason`	`string`	Да	Required. Shown in the case, the mod log and the member’s DM 1–500 символов
`evidence`	`array of string`	Нет	Up to 5 links до 5 элементов

Ответ

Поля ответа · 202
Поле	Тип	Обязательное	Описание
`actionId`	`string`	Да
`action`	`string`	Да	Одно из `warn`, `timeout`, `untimeout`, `kick`, `ban`, `unban`
`userId`	`string`	Да
`status`	`string`	Да	Одно из `pending`, `running`, `done`, `failed`
`caseNumber`	`integer \| null`	Да
`error`	`string \| null`	Да	Refusal code when failed (e.g. HIERARCHY_HIGHER, MODERATOR_MISSING_PERMISSION, NOT_BANNED, BOT_MISSING_PERMISSIONS)
`requestedAt`	`string \| null`	Да	ISO 8601 date-time

Ответ · 202

{
  "actionId": "234567890123456789",
  "action": "warn",
  "userId": "876543210987654321",
  "status": "pending",
  "caseNumber": 10,
  "error": "example",
  "requestedAt": "2026-10-07T12:00:00.000Z"
}

Примеры

curl

curl -s -X POST "https://console.botgg.app/api/v1/guilds/123456789012345678/moderation/users/876543210987654321/warn" \
  -H "Authorization: Bearer $BOTGG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"reason":"Tournament prize","evidence":["example"]}'

JavaScript (fetch)

// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/moderation/users/876543210987654321/warn', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(), // reuse it when you retry this request
  },
  body: JSON.stringify({
    reason: 'Tournament prize',
    evidence: [
      'example',
    ],
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);

Python (requests)

import os, uuid
import requests

res = requests.post(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/moderation/users/876543210987654321/warn",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),  # reuse it when you retry this request
    },
    json={
        "reason": "Tournament prize",
        "evidence": [
            "example",
        ],
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

Ошибки

Ошибки
HTTP	Коды
400	`INVALID_JSON`
403	`MODERATOR_NOT_MEMBER`, `MODERATOR_MISSING_PERMISSION`, `HIERARCHY`
404	`MEMBER_NOT_FOUND`
409	`FEATURE_DISABLED`, `NOT_BANNED`, `BOT_MISSING_PERMISSIONS`
413	`PAYLOAD_TOO_LARGE`
415	`UNSUPPORTED_MEDIA_TYPE`
422	`IDEMPOTENCY_KEY_REUSED`
503	`SERVICE_UNAVAILABLE`

Time out a member

POST/guilds/{guildId}/moderation/users/{userId}/timeout

Право: moderation:writeЧувствительноеIdempotency-Key

Same as /timeout: Discord timeout for durationSeconds, a case, DM per the settings. Acts in the name of the key’s creator, who must still have the matching Discord permission; the target must be below their and the bot’s highest role (never the owner, the bot or the creator). The bot runs it within a few seconds — poll GET …/moderation/actions/{actionId}. At most 10 actions a minute per key. Written to the audit log.

На сервере должен быть включён модуль: Модерация

Параметры
Имя	Где	Тип	Обязательное	Описание
`guildId`	путь	`string`	Да	ID вашего сервера · Discord ID (строка)
`userId`	путь	`string`	Да	Discord ID участника · Discord ID (строка)
`Idempotency-Key`	заголовок	`string`	Нет	Необязательно. Передайте уникальное значение (UUID) и повторяйте его при ретраях — операция выполнится один раз. Как это работает

Тело запроса

Тело запроса
Поле	Тип	Обязательное	Описание
`reason`	`string`	Да	Required. Shown in the case, the mod log and the member’s DM 1–500 символов
`durationSeconds`	`integer`	Да	1 minute to 28 days 60–2 419 200
`evidence`	`array of string`	Нет	Up to 5 links до 5 элементов

Ответ

Поля ответа · 202
Поле	Тип	Обязательное	Описание
`actionId`	`string`	Да
`action`	`string`	Да	Одно из `warn`, `timeout`, `untimeout`, `kick`, `ban`, `unban`
`userId`	`string`	Да
`status`	`string`	Да	Одно из `pending`, `running`, `done`, `failed`
`caseNumber`	`integer \| null`	Да
`error`	`string \| null`	Да	Refusal code when failed (e.g. HIERARCHY_HIGHER, MODERATOR_MISSING_PERMISSION, NOT_BANNED, BOT_MISSING_PERMISSIONS)
`requestedAt`	`string \| null`	Да	ISO 8601 date-time

Ответ · 202

{
  "actionId": "234567890123456789",
  "action": "warn",
  "userId": "876543210987654321",
  "status": "pending",
  "caseNumber": 10,
  "error": "example",
  "requestedAt": "2026-10-07T12:00:00.000Z"
}

Примеры

curl

curl -s -X POST "https://console.botgg.app/api/v1/guilds/123456789012345678/moderation/users/876543210987654321/timeout" \
  -H "Authorization: Bearer $BOTGG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"reason":"Tournament prize","durationSeconds":3600,"evidence":["example"]}'

JavaScript (fetch)

// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/moderation/users/876543210987654321/timeout', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(), // reuse it when you retry this request
  },
  body: JSON.stringify({
    reason: 'Tournament prize',
    durationSeconds: 3600,
    evidence: [
      'example',
    ],
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);

Python (requests)

import os, uuid
import requests

res = requests.post(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/moderation/users/876543210987654321/timeout",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),  # reuse it when you retry this request
    },
    json={
        "reason": "Tournament prize",
        "durationSeconds": 3600,
        "evidence": [
            "example",
        ],
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

Ошибки

Ошибки
HTTP	Коды
400	`INVALID_JSON`
403	`MODERATOR_NOT_MEMBER`, `MODERATOR_MISSING_PERMISSION`, `HIERARCHY`
404	`MEMBER_NOT_FOUND`
409	`FEATURE_DISABLED`, `NOT_BANNED`, `BOT_MISSING_PERMISSIONS`
413	`PAYLOAD_TOO_LARGE`
415	`UNSUPPORTED_MEDIA_TYPE`
422	`IDEMPOTENCY_KEY_REUSED`
503	`SERVICE_UNAVAILABLE`

Remove a member’s timeout

POST/guilds/{guildId}/moderation/users/{userId}/untimeout

Право: moderation:writeЧувствительноеIdempotency-Key

Same as /untimeout. Acts in the name of the key’s creator, who must still have the matching Discord permission; the target must be below their and the bot’s highest role (never the owner, the bot or the creator). The bot runs it within a few seconds — poll GET …/moderation/actions/{actionId}. At most 10 actions a minute per key. Written to the audit log.

На сервере должен быть включён модуль: Модерация

Параметры
Имя	Где	Тип	Обязательное	Описание
`guildId`	путь	`string`	Да	ID вашего сервера · Discord ID (строка)
`userId`	путь	`string`	Да	Discord ID участника · Discord ID (строка)
`Idempotency-Key`	заголовок	`string`	Нет	Необязательно. Передайте уникальное значение (UUID) и повторяйте его при ретраях — операция выполнится один раз. Как это работает

Тело запроса

Тело запроса
Поле	Тип	Обязательное	Описание
`reason`	`string`	Да	Required. Shown in the case, the mod log and the member’s DM 1–500 символов

Ответ

Поля ответа · 202
Поле	Тип	Обязательное	Описание
`actionId`	`string`	Да
`action`	`string`	Да	Одно из `warn`, `timeout`, `untimeout`, `kick`, `ban`, `unban`
`userId`	`string`	Да
`status`	`string`	Да	Одно из `pending`, `running`, `done`, `failed`
`caseNumber`	`integer \| null`	Да
`error`	`string \| null`	Да	Refusal code when failed (e.g. HIERARCHY_HIGHER, MODERATOR_MISSING_PERMISSION, NOT_BANNED, BOT_MISSING_PERMISSIONS)
`requestedAt`	`string \| null`	Да	ISO 8601 date-time

Ответ · 202

{
  "actionId": "234567890123456789",
  "action": "warn",
  "userId": "876543210987654321",
  "status": "pending",
  "caseNumber": 10,
  "error": "example",
  "requestedAt": "2026-10-07T12:00:00.000Z"
}

Примеры

curl

curl -s -X POST "https://console.botgg.app/api/v1/guilds/123456789012345678/moderation/users/876543210987654321/untimeout" \
  -H "Authorization: Bearer $BOTGG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"reason":"Tournament prize"}'

JavaScript (fetch)

// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/moderation/users/876543210987654321/untimeout', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(), // reuse it when you retry this request
  },
  body: JSON.stringify({
    reason: 'Tournament prize',
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);

Python (requests)

import os, uuid
import requests

res = requests.post(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/moderation/users/876543210987654321/untimeout",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),  # reuse it when you retry this request
    },
    json={
        "reason": "Tournament prize",
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

Ошибки

Ошибки
HTTP	Коды
400	`INVALID_JSON`
403	`MODERATOR_NOT_MEMBER`, `MODERATOR_MISSING_PERMISSION`, `HIERARCHY`
404	`MEMBER_NOT_FOUND`
409	`FEATURE_DISABLED`, `NOT_BANNED`, `BOT_MISSING_PERMISSIONS`
413	`PAYLOAD_TOO_LARGE`
415	`UNSUPPORTED_MEDIA_TYPE`
422	`IDEMPOTENCY_KEY_REUSED`
503	`SERVICE_UNAVAILABLE`

Kick a member

POST/guilds/{guildId}/moderation/users/{userId}/kick

Право: moderation:writeЧувствительноеIdempotency-Key

Same as /kick: DM (before the kick) per the settings, then the kick and a case. Acts in the name of the key’s creator, who must still have the matching Discord permission; the target must be below their and the bot’s highest role (never the owner, the bot or the creator). The bot runs it within a few seconds — poll GET …/moderation/actions/{actionId}. At most 10 actions a minute per key. Written to the audit log.

На сервере должен быть включён модуль: Модерация

Параметры
Имя	Где	Тип	Обязательное	Описание
`guildId`	путь	`string`	Да	ID вашего сервера · Discord ID (строка)
`userId`	путь	`string`	Да	Discord ID участника · Discord ID (строка)
`Idempotency-Key`	заголовок	`string`	Нет	Необязательно. Передайте уникальное значение (UUID) и повторяйте его при ретраях — операция выполнится один раз. Как это работает

Тело запроса

Тело запроса
Поле	Тип	Обязательное	Описание
`reason`	`string`	Да	Required. Shown in the case, the mod log and the member’s DM 1–500 символов
`evidence`	`array of string`	Нет	Up to 5 links до 5 элементов

Ответ

Поля ответа · 202
Поле	Тип	Обязательное	Описание
`actionId`	`string`	Да
`action`	`string`	Да	Одно из `warn`, `timeout`, `untimeout`, `kick`, `ban`, `unban`
`userId`	`string`	Да
`status`	`string`	Да	Одно из `pending`, `running`, `done`, `failed`
`caseNumber`	`integer \| null`	Да
`error`	`string \| null`	Да	Refusal code when failed (e.g. HIERARCHY_HIGHER, MODERATOR_MISSING_PERMISSION, NOT_BANNED, BOT_MISSING_PERMISSIONS)
`requestedAt`	`string \| null`	Да	ISO 8601 date-time

Ответ · 202

{
  "actionId": "234567890123456789",
  "action": "warn",
  "userId": "876543210987654321",
  "status": "pending",
  "caseNumber": 10,
  "error": "example",
  "requestedAt": "2026-10-07T12:00:00.000Z"
}

Примеры

curl

curl -s -X POST "https://console.botgg.app/api/v1/guilds/123456789012345678/moderation/users/876543210987654321/kick" \
  -H "Authorization: Bearer $BOTGG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"reason":"Tournament prize","evidence":["example"]}'

JavaScript (fetch)

// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/moderation/users/876543210987654321/kick', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(), // reuse it when you retry this request
  },
  body: JSON.stringify({
    reason: 'Tournament prize',
    evidence: [
      'example',
    ],
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);

Python (requests)

import os, uuid
import requests

res = requests.post(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/moderation/users/876543210987654321/kick",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),  # reuse it when you retry this request
    },
    json={
        "reason": "Tournament prize",
        "evidence": [
            "example",
        ],
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

Ошибки

Ошибки
HTTP	Коды
400	`INVALID_JSON`
403	`MODERATOR_NOT_MEMBER`, `MODERATOR_MISSING_PERMISSION`, `HIERARCHY`
404	`MEMBER_NOT_FOUND`
409	`FEATURE_DISABLED`, `NOT_BANNED`, `BOT_MISSING_PERMISSIONS`
413	`PAYLOAD_TOO_LARGE`
415	`UNSUPPORTED_MEDIA_TYPE`
422	`IDEMPOTENCY_KEY_REUSED`
503	`SERVICE_UNAVAILABLE`

Ban a user

POST/guilds/{guildId}/moderation/users/{userId}/ban

Право: moderation:writeЧувствительноеIdempotency-Key

Same as /ban: with durationSeconds a temporary ban the bot lifts automatically; deleteMessageSeconds deletes recent messages. Works for users who already left. Acts in the name of the key’s creator, who must still have the matching Discord permission; the target must be below their and the bot’s highest role (never the owner, the bot or the creator). The bot runs it within a few seconds — poll GET …/moderation/actions/{actionId}. At most 10 actions a minute per key. Written to the audit log.

На сервере должен быть включён модуль: Модерация

Параметры
Имя	Где	Тип	Обязательное	Описание
`guildId`	путь	`string`	Да	ID вашего сервера · Discord ID (строка)
`userId`	путь	`string`	Да	Discord ID участника · Discord ID (строка)
`Idempotency-Key`	заголовок	`string`	Нет	Необязательно. Передайте уникальное значение (UUID) и повторяйте его при ретраях — операция выполнится один раз. Как это работает

Тело запроса

Тело запроса
Поле	Тип	Обязательное	Описание
`reason`	`string`	Да	Required. Shown in the case, the mod log and the member’s DM 1–500 символов
`deleteMessageSeconds`	`integer`	Нет	Delete the user’s messages of the last N seconds (≤ 7 days) 0–604 800
`durationSeconds`	`integer \| null`	Нет	Temporary ban (≤ 365 days); omit for a permanent ban 60–31 536 000
`evidence`	`array of string`	Нет	Up to 5 links до 5 элементов

Ответ

Поля ответа · 202
Поле	Тип	Обязательное	Описание
`actionId`	`string`	Да
`action`	`string`	Да	Одно из `warn`, `timeout`, `untimeout`, `kick`, `ban`, `unban`
`userId`	`string`	Да
`status`	`string`	Да	Одно из `pending`, `running`, `done`, `failed`
`caseNumber`	`integer \| null`	Да
`error`	`string \| null`	Да	Refusal code when failed (e.g. HIERARCHY_HIGHER, MODERATOR_MISSING_PERMISSION, NOT_BANNED, BOT_MISSING_PERMISSIONS)
`requestedAt`	`string \| null`	Да	ISO 8601 date-time

Ответ · 202

{
  "actionId": "234567890123456789",
  "action": "warn",
  "userId": "876543210987654321",
  "status": "pending",
  "caseNumber": 10,
  "error": "example",
  "requestedAt": "2026-10-07T12:00:00.000Z"
}

Примеры

curl

curl -s -X POST "https://console.botgg.app/api/v1/guilds/123456789012345678/moderation/users/876543210987654321/ban" \
  -H "Authorization: Bearer $BOTGG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"reason":"Tournament prize","deleteMessageSeconds":3600,"durationSeconds":3600,"evidence":["example"]}'

JavaScript (fetch)

// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/moderation/users/876543210987654321/ban', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(), // reuse it when you retry this request
  },
  body: JSON.stringify({
    reason: 'Tournament prize',
    deleteMessageSeconds: 3600,
    durationSeconds: 3600,
    evidence: [
      'example',
    ],
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);

Python (requests)

import os, uuid
import requests

res = requests.post(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/moderation/users/876543210987654321/ban",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),  # reuse it when you retry this request
    },
    json={
        "reason": "Tournament prize",
        "deleteMessageSeconds": 3600,
        "durationSeconds": 3600,
        "evidence": [
            "example",
        ],
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

Ошибки

Ошибки
HTTP	Коды
400	`INVALID_JSON`
403	`MODERATOR_NOT_MEMBER`, `MODERATOR_MISSING_PERMISSION`, `HIERARCHY`
404	`MEMBER_NOT_FOUND`
409	`FEATURE_DISABLED`, `NOT_BANNED`, `BOT_MISSING_PERMISSIONS`
413	`PAYLOAD_TOO_LARGE`
415	`UNSUPPORTED_MEDIA_TYPE`
422	`IDEMPOTENCY_KEY_REUSED`
503	`SERVICE_UNAVAILABLE`

Unban a user

POST/guilds/{guildId}/moderation/users/{userId}/unban

Право: moderation:writeЧувствительноеIdempotency-Key

Same as /unban (ends a running tempban). 409 NOT_BANNED when the user isn’t banned. Acts in the name of the key’s creator, who must still have the matching Discord permission; the target must be below their and the bot’s highest role (never the owner, the bot or the creator). The bot runs it within a few seconds — poll GET …/moderation/actions/{actionId}. At most 10 actions a minute per key. Written to the audit log.

На сервере должен быть включён модуль: Модерация

Параметры
Имя	Где	Тип	Обязательное	Описание
`guildId`	путь	`string`	Да	ID вашего сервера · Discord ID (строка)
`userId`	путь	`string`	Да	Discord ID участника · Discord ID (строка)
`Idempotency-Key`	заголовок	`string`	Нет	Необязательно. Передайте уникальное значение (UUID) и повторяйте его при ретраях — операция выполнится один раз. Как это работает

Тело запроса

Тело запроса
Поле	Тип	Обязательное	Описание
`reason`	`string`	Да	Required. Shown in the case, the mod log and the member’s DM 1–500 символов

Ответ

Поля ответа · 202
Поле	Тип	Обязательное	Описание
`actionId`	`string`	Да
`action`	`string`	Да	Одно из `warn`, `timeout`, `untimeout`, `kick`, `ban`, `unban`
`userId`	`string`	Да
`status`	`string`	Да	Одно из `pending`, `running`, `done`, `failed`
`caseNumber`	`integer \| null`	Да
`error`	`string \| null`	Да	Refusal code when failed (e.g. HIERARCHY_HIGHER, MODERATOR_MISSING_PERMISSION, NOT_BANNED, BOT_MISSING_PERMISSIONS)
`requestedAt`	`string \| null`	Да	ISO 8601 date-time

Ответ · 202

{
  "actionId": "234567890123456789",
  "action": "warn",
  "userId": "876543210987654321",
  "status": "pending",
  "caseNumber": 10,
  "error": "example",
  "requestedAt": "2026-10-07T12:00:00.000Z"
}

Примеры

curl

curl -s -X POST "https://console.botgg.app/api/v1/guilds/123456789012345678/moderation/users/876543210987654321/unban" \
  -H "Authorization: Bearer $BOTGG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"reason":"Tournament prize"}'

JavaScript (fetch)

// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/moderation/users/876543210987654321/unban', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(), // reuse it when you retry this request
  },
  body: JSON.stringify({
    reason: 'Tournament prize',
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);

Python (requests)

import os, uuid
import requests

res = requests.post(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/moderation/users/876543210987654321/unban",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),  # reuse it when you retry this request
    },
    json={
        "reason": "Tournament prize",
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

Ошибки

Ошибки
HTTP	Коды
400	`INVALID_JSON`
403	`MODERATOR_NOT_MEMBER`, `MODERATOR_MISSING_PERMISSION`, `HIERARCHY`
404	`MEMBER_NOT_FOUND`
409	`FEATURE_DISABLED`, `NOT_BANNED`, `BOT_MISSING_PERMISSIONS`
413	`PAYLOAD_TOO_LARGE`
415	`UNSUPPORTED_MEDIA_TYPE`
422	`IDEMPOTENCY_KEY_REUSED`
503	`SERVICE_UNAVAILABLE`

Get the result of a moderation action

GET/guilds/{guildId}/moderation/actions/{actionId}

Право: moderation:writeЧувствительное

Only actions made with the same API key. done → caseNumber; failed → error (the bot re-checks everything right before acting).

На сервере должен быть включён модуль: Модерация

Параметры
Имя	Где	Тип	Обязательное	Описание
`guildId`	путь	`string`	Да	ID вашего сервера · Discord ID (строка)
`actionId`	путь	`string`	Да

Ответ

Поля ответа · 200
Поле	Тип	Обязательное	Описание
`actionId`	`string`	Да
`action`	`string`	Да	Одно из `warn`, `timeout`, `untimeout`, `kick`, `ban`, `unban`
`userId`	`string`	Да
`status`	`string`	Да	Одно из `pending`, `running`, `done`, `failed`
`caseNumber`	`integer \| null`	Да
`error`	`string \| null`	Да	Refusal code when failed (e.g. HIERARCHY_HIGHER, MODERATOR_MISSING_PERMISSION, NOT_BANNED, BOT_MISSING_PERMISSIONS)
`requestedAt`	`string \| null`	Да	ISO 8601 date-time

Ответ · 200

{
  "actionId": "234567890123456789",
  "action": "warn",
  "userId": "876543210987654321",
  "status": "pending",
  "caseNumber": 10,
  "error": "example",
  "requestedAt": "2026-10-07T12:00:00.000Z"
}

Примеры

curl

curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/moderation/actions/234567890123456789" \
  -H "Authorization: Bearer $BOTGG_API_KEY"

JavaScript (fetch)

// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/moderation/actions/234567890123456789', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);

Python (requests)

import os
import requests

res = requests.get(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/moderation/actions/234567890123456789",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

Ошибки

Ошибки
HTTP	Коды
404	`MODERATION_ACTION_NOT_FOUND`
409	`FEATURE_DISABLED`
503	`SERVICE_UNAVAILABLE`

Эндпоинты

List moderation cases

Ответ

Примеры

Ошибки

Get a moderation case

Ответ

Примеры

Ошибки

Warn a member

Тело запроса

Ответ

Примеры

Ошибки

Time out a member

Тело запроса

Ответ

Примеры

Ошибки

Remove a member’s timeout

Тело запроса

Ответ

Примеры

Ошибки

Kick a member

Тело запроса

Ответ

Примеры

Ошибки

Ban a user

Тело запроса

Ответ

Примеры

Ошибки

Unban a user

Тело запроса

Ответ

Примеры

Ошибки

Get the result of a moderation action

Ответ

Примеры

Ошибки

Готовы прокачать свой сервер?