Справочник API: Апелляции на бан

Эндпоинты

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

Эндпоинты: Апелляции на бан
Эндпоинт	Право	Описание
GET`/guilds/{guildId}/appeals`	`appeals:read`	List ban appeals
GET`/guilds/{guildId}/appeals/{number}`	`appeals:read`	Get a ban appeal
POST`/guilds/{guildId}/appeals/{number}/approve`	`appeals:write`	Approve a ban appeal (unban)
POST`/guilds/{guildId}/appeals/{number}/reject`	`appeals:write`	Reject a ban appeal

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

Ошибки
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 ban appeals

GET/guilds/{guildId}/appeals

Право: appeals:read

Newest first. status=open (default) = open + waiting for the user’s answer; all = every status. Pass before=<nextCursor> for the next page.

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

Параметры
Имя	Где	Тип	Обязательное	Описание
`guildId`	путь	`string`	Да	ID вашего сервера · Discord ID (строка)
`status`	query	`string`	Нет	Одно из `open`, `question`, `approved`, `rejected`, `closed`, `all` · По умолчанию `"open"`
`userId`	query	`string`	Нет	Only this user’s appeals Discord ID (строка)
`limit`	query	`integer`	Нет	1–100 · По умолчанию `25`
`before`	query	`integer`	Нет	1–999 999 999

Ответ

Поля ответа · 200
Поле	Тип	Обязательное	Описание
`items`	`array of object`	Да
`items[].number`	`integer`	Да
`items[].userId`	`string`	Да
`items[].userTag`	`string \| null`	Да
`items[].status`	`string`	Да	Одно из `open`, `question`, `approved`, `rejected`, `closed`
`items[].banCaseNumber`	`integer \| null`	Да
`items[].claimedBy`	`string \| null`	Да
`items[].decidedBy`	`string \| null`	Да	null = system / API
`items[].decidedAt`	`string \| null`	Да	ISO 8601 date-time
`items[].reason`	`string \| null`	Да
`items[].createdAt`	`string \| null`	Да	ISO 8601 date-time
`items[].lastActivityAt`	`string \| null`	Да	ISO 8601 date-time
`nextCursor`	`string \| null`	Да

Ответ · 200

{
  "items": [
    {
      "number": 7,
      "userId": "876543210987654321",
      "userTag": "example",
      "status": "open",
      "banCaseNumber": 10,
      "claimedBy": "example",
      "decidedBy": "example",
      "decidedAt": "2026-10-07T12:00:00.000Z",
      "reason": "Tournament prize",
      "createdAt": "2026-10-07T12:00:00.000Z",
      "lastActivityAt": "2026-10-07T12:00:00.000Z"
    }
  ],
  "nextCursor": "98700"
}

Примеры

curl

curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/appeals?status=open&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/appeals?status=open&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/appeals",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
    },
    params={
        "status": "open",
        "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 ban appeal

GET/guilds/{guildId}/appeals/{number}

Право: appeals:read

With the answers, the ban reason and the conversation the appellant sees. Internal staff notes are never returned.

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

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

Ответ

Поля ответа · 200
Поле	Тип	Обязательное	Описание
`number`	`integer`	Да
`userId`	`string`	Да
`userTag`	`string \| null`	Да
`status`	`string`	Да	Одно из `open`, `question`, `approved`, `rejected`, `closed`
`banCaseNumber`	`integer \| null`	Да
`claimedBy`	`string \| null`	Да
`decidedBy`	`string \| null`	Да	null = system / API
`decidedAt`	`string \| null`	Да	ISO 8601 date-time
`reason`	`string \| null`	Да
`createdAt`	`string \| null`	Да	ISO 8601 date-time
`lastActivityAt`	`string \| null`	Да	ISO 8601 date-time
`banReason`	`string \| null`	Да
`answers`	`array of object`	Да
`answers[].id`	`string`	Да
`answers[].type`	`string`	Да
`answers[].label`	`string`	Да
`answers[].value`	`any`	Да
`messages`	`array of object`	Да	The conversation the appellant sees (staff questions + replies). Internal notes are never included.
`messages[].author`	`string`	Да	Одно из `user`, `staff`
`messages[].authorId`	`string \| null`	Да
`messages[].text`	`string`	Да
`messages[].createdAt`	`string \| null`	Да	ISO 8601 date-time
`applying`	`boolean`	Да	A console/API decision is still being applied in Discord
`failedAction`	`object \| null`	Да
`failedAction.type`	`string`	Да
`failedAction.error`	`string \| null`	Да

Ответ · 200

{
  "number": 7,
  "userId": "876543210987654321",
  "userTag": "example",
  "status": "open",
  "banCaseNumber": 10,
  "claimedBy": "example",
  "decidedBy": "example",
  "decidedAt": "2026-10-07T12:00:00.000Z",
  "reason": "Tournament prize",
  "createdAt": "2026-10-07T12:00:00.000Z",
  "lastActivityAt": "2026-10-07T12:00:00.000Z",
  "banReason": "example",
  "answers": [
    {
      "id": "example",
      "type": "example",
      "label": "Example",
      "value": null
    }
  ],
  "messages": [
    {
      "author": "user",
      "authorId": "234567890123456789",
      "text": "Example answer",
      "createdAt": "2026-10-07T12:00:00.000Z"
    }
  ],
  "applying": true,
  "failedAction": {
    "type": "example",
    "error": "example"
  }
}

Примеры

curl

curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/appeals/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/appeals/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/appeals/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	`APPEAL_NOT_FOUND`
409	`FEATURE_DISABLED`
503	`SERVICE_UNAVAILABLE`

Approve a ban appeal (unban)

POST/guilds/{guildId}/appeals/{number}/approve

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

Same as Approve in the console: the bot unbans within a few seconds (an unban moderation case when Moderation is enabled), creates a single-use invite and DMs the user per the appeal settings. Written to the audit log.

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

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

Тело запроса

Тело запроса
Поле	Тип	Обязательное	Описание
`reason`	`string \| null`	Нет	Sent to the appellant (DM / appeal page) до 1 000 символов

Ответ

Поля ответа · 202
Поле	Тип	Обязательное	Описание
`number`	`integer`	Да
`userId`	`string`	Да
`userTag`	`string \| null`	Да
`status`	`string`	Да	Одно из `open`, `question`, `approved`, `rejected`, `closed`
`banCaseNumber`	`integer \| null`	Да
`claimedBy`	`string \| null`	Да
`decidedBy`	`string \| null`	Да	null = system / API
`decidedAt`	`string \| null`	Да	ISO 8601 date-time
`reason`	`string \| null`	Да
`createdAt`	`string \| null`	Да	ISO 8601 date-time
`lastActivityAt`	`string \| null`	Да	ISO 8601 date-time
`banReason`	`string \| null`	Да
`answers`	`array of object`	Да
`answers[].id`	`string`	Да
`answers[].type`	`string`	Да
`answers[].label`	`string`	Да
`answers[].value`	`any`	Да
`messages`	`array of object`	Да	The conversation the appellant sees (staff questions + replies). Internal notes are never included.
`messages[].author`	`string`	Да	Одно из `user`, `staff`
`messages[].authorId`	`string \| null`	Да
`messages[].text`	`string`	Да
`messages[].createdAt`	`string \| null`	Да	ISO 8601 date-time
`applying`	`boolean`	Да	A console/API decision is still being applied in Discord
`failedAction`	`object \| null`	Да
`failedAction.type`	`string`	Да
`failedAction.error`	`string \| null`	Да

Ответ · 202

{
  "number": 7,
  "userId": "876543210987654321",
  "userTag": "example",
  "status": "open",
  "banCaseNumber": 10,
  "claimedBy": "example",
  "decidedBy": "example",
  "decidedAt": "2026-10-07T12:00:00.000Z",
  "reason": "Tournament prize",
  "createdAt": "2026-10-07T12:00:00.000Z",
  "lastActivityAt": "2026-10-07T12:00:00.000Z",
  "banReason": "example",
  "answers": [
    {
      "id": "example",
      "type": "example",
      "label": "Example",
      "value": null
    }
  ],
  "messages": [
    {
      "author": "user",
      "authorId": "234567890123456789",
      "text": "Example answer",
      "createdAt": "2026-10-07T12:00:00.000Z"
    }
  ],
  "applying": true,
  "failedAction": {
    "type": "example",
    "error": "example"
  }
}

Примеры

curl

curl -s -X POST "https://console.botgg.app/api/v1/guilds/123456789012345678/appeals/234567890123456789/approve" \
  -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/appeals/234567890123456789/approve', {
  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/appeals/234567890123456789/approve",
    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	`SELF_DECISION`
404	`APPEAL_NOT_FOUND`
409	`FEATURE_DISABLED`, `ALREADY_DECIDED`
413	`PAYLOAD_TOO_LARGE`
415	`UNSUPPORTED_MEDIA_TYPE`
422	`IDEMPOTENCY_KEY_REUSED`
503	`SERVICE_UNAVAILABLE`

Reject a ban appeal

POST/guilds/{guildId}/appeals/{number}/reject

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

Same as Reject in the console: the user gets the rejection DM per the appeal settings and the re-appeal cooldown starts. Written to the audit log.

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

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

Тело запроса

Тело запроса
Поле	Тип	Обязательное	Описание
`reason`	`string \| null`	Нет	Sent to the appellant (DM / appeal page) до 1 000 символов

Ответ

Поля ответа · 202
Поле	Тип	Обязательное	Описание
`number`	`integer`	Да
`userId`	`string`	Да
`userTag`	`string \| null`	Да
`status`	`string`	Да	Одно из `open`, `question`, `approved`, `rejected`, `closed`
`banCaseNumber`	`integer \| null`	Да
`claimedBy`	`string \| null`	Да
`decidedBy`	`string \| null`	Да	null = system / API
`decidedAt`	`string \| null`	Да	ISO 8601 date-time
`reason`	`string \| null`	Да
`createdAt`	`string \| null`	Да	ISO 8601 date-time
`lastActivityAt`	`string \| null`	Да	ISO 8601 date-time
`banReason`	`string \| null`	Да
`answers`	`array of object`	Да
`answers[].id`	`string`	Да
`answers[].type`	`string`	Да
`answers[].label`	`string`	Да
`answers[].value`	`any`	Да
`messages`	`array of object`	Да	The conversation the appellant sees (staff questions + replies). Internal notes are never included.
`messages[].author`	`string`	Да	Одно из `user`, `staff`
`messages[].authorId`	`string \| null`	Да
`messages[].text`	`string`	Да
`messages[].createdAt`	`string \| null`	Да	ISO 8601 date-time
`applying`	`boolean`	Да	A console/API decision is still being applied in Discord
`failedAction`	`object \| null`	Да
`failedAction.type`	`string`	Да
`failedAction.error`	`string \| null`	Да

Ответ · 202

{
  "number": 7,
  "userId": "876543210987654321",
  "userTag": "example",
  "status": "open",
  "banCaseNumber": 10,
  "claimedBy": "example",
  "decidedBy": "example",
  "decidedAt": "2026-10-07T12:00:00.000Z",
  "reason": "Tournament prize",
  "createdAt": "2026-10-07T12:00:00.000Z",
  "lastActivityAt": "2026-10-07T12:00:00.000Z",
  "banReason": "example",
  "answers": [
    {
      "id": "example",
      "type": "example",
      "label": "Example",
      "value": null
    }
  ],
  "messages": [
    {
      "author": "user",
      "authorId": "234567890123456789",
      "text": "Example answer",
      "createdAt": "2026-10-07T12:00:00.000Z"
    }
  ],
  "applying": true,
  "failedAction": {
    "type": "example",
    "error": "example"
  }
}

Примеры

curl

curl -s -X POST "https://console.botgg.app/api/v1/guilds/123456789012345678/appeals/234567890123456789/reject" \
  -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/appeals/234567890123456789/reject', {
  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/appeals/234567890123456789/reject",
    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	`SELF_DECISION`
404	`APPEAL_NOT_FOUND`
409	`FEATURE_DISABLED`, `ALREADY_DECIDED`
413	`PAYLOAD_TOO_LARGE`
415	`UNSUPPORTED_MEDIA_TYPE`
422	`IDEMPOTENCY_KEY_REUSED`
503	`SERVICE_UNAVAILABLE`

Эндпоинты

List ban appeals

Ответ

Примеры

Ошибки

Get a ban appeal

Ответ

Примеры

Ошибки

Approve a ban appeal (unban)

Тело запроса

Ответ

Примеры

Ошибки

Reject a ban appeal

Тело запроса

Ответ

Примеры

Ошибки

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