REST API v1 · 開發者 · API 參考

管理 API 參考

BotGG REST API v1 的所有 9 個 管理 端點:範圍、參數、欄位、錯誤,以及可直接執行的 curl、JavaScript 與 Python 範例。

開發者文件
本頁目錄

端點

路徑皆相對於 https://console.botgg.app/api/v1。請以 Authorization: Bearer botgg_… 傳送你的 API 金鑰,ID 皆為字串。

管理 端點
端點範圍說明
GET/guilds/{guildId}/moderation/casesmoderation:readList moderation cases
GET/guilds/{guildId}/moderation/cases/{number}moderation:readGet a moderation case
POST/guilds/{guildId}/moderation/users/{userId}/warnmoderation:writeWarn a member
POST/guilds/{guildId}/moderation/users/{userId}/timeoutmoderation:writeTime out a member
POST/guilds/{guildId}/moderation/users/{userId}/untimeoutmoderation:writeRemove a member’s timeout
POST/guilds/{guildId}/moderation/users/{userId}/kickmoderation:writeKick a member
POST/guilds/{guildId}/moderation/users/{userId}/banmoderation:writeBan a user
POST/guilds/{guildId}/moderation/users/{userId}/unbanmoderation:writeUnban a user
GET/guilds/{guildId}/moderation/actions/{actionId}moderation:writeGet the result of a moderation action

除了下方各自的錯誤外,每個端點還可能回傳這些常見錯誤:

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查詢字串string否其中之一 warn, timeout, untimeout, kick, ban, tempban, softban, unban, note, purge
source查詢字串string否其中之一 command, automod, escalation, antiraid, antinuke, console, api, flow
userId查詢字串string否Only cases against this user
Discord ID(字串)
moderatorId查詢字串string否Discord ID(字串)
active查詢字串string否1 = only running warnings / timeouts / tempbans
其中之一 1, 0, true, false
limit查詢字串integer否1–100 · 預設值 25
before查詢字串integer否1–999,999,999

回應

回應欄位 · 200
欄位類型必填說明
itemsarray of object是
items[].numberinteger是
items[].actionstring是其中之一 warn, timeout, untimeout, kick, ban, tempban, softban, unban, note, purge
items[].userIdstring是The target
items[].userTagstring | null是
items[].moderatorIdstring是
items[].reasonstring | null是
items[].durationSecondsinteger | null是
items[].evidencearray of string是
items[].sourcestring是其中之一 command, automod, escalation, antiraid, antinuke, console, api, flow
items[].activeboolean是
items[].expiresAtstring | null是ISO 8601 date-time
items[].resolvedAtstring | null是ISO 8601 date-time
items[].dmStatusstring | null是其中之一 sent, failed, off
items[].apiKeyobject | null是Set when the action was made with an API key
items[].apiKey.idinteger | null是
items[].apiKey.namestring | null是
items[].createdAtstring | null是ISO 8601 date-time
nextCursorstring | 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)

錯誤

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
欄位類型必填說明
numberinteger是
actionstring是其中之一 warn, timeout, untimeout, kick, ban, tempban, softban, unban, note, purge
userIdstring是The target
userTagstring | null是
moderatorIdstring是
reasonstring | null是
durationSecondsinteger | null是
evidencearray of string是
sourcestring是其中之一 command, automod, escalation, antiraid, antinuke, console, api, flow
activeboolean是
expiresAtstring | null是ISO 8601 date-time
resolvedAtstring | null是ISO 8601 date-time
dmStatusstring | null是其中之一 sent, failed, off
apiKeyobject | null是Set when the action was made with an API key
apiKey.idinteger | null是
apiKey.namestring | null是
createdAtstring | null是ISO 8601 date-time
eventsarray of object是
events[].typestring是
events[].actorIdstring | null是
events[].dataany是
events[].createdAtstring | 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)

錯誤

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),重試時沿用同一個值,變更就只會發生一次。 運作方式

請求內容

請求內容
欄位類型必填說明
reasonstring是Required. Shown in the case, the mod log and the member’s DM
1–500 個字元
evidencearray of string否Up to 5 links
最多 5 個項目

回應

回應欄位 · 202
欄位類型必填說明
actionIdstring是
actionstring是其中之一 warn, timeout, untimeout, kick, ban, unban
userIdstring是
statusstring是其中之一 pending, running, done, failed
caseNumberinteger | null是
errorstring | null是Refusal code when failed (e.g. HIERARCHY_HIGHER, MODERATOR_MISSING_PERMISSION, NOT_BANNED, BOT_MISSING_PERMISSIONS)
requestedAtstring | 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)

錯誤

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),重試時沿用同一個值,變更就只會發生一次。 運作方式

請求內容

請求內容
欄位類型必填說明
reasonstring是Required. Shown in the case, the mod log and the member’s DM
1–500 個字元
durationSecondsinteger是1 minute to 28 days
60–2,419,200
evidencearray of string否Up to 5 links
最多 5 個項目

回應

回應欄位 · 202
欄位類型必填說明
actionIdstring是
actionstring是其中之一 warn, timeout, untimeout, kick, ban, unban
userIdstring是
statusstring是其中之一 pending, running, done, failed
caseNumberinteger | null是
errorstring | null是Refusal code when failed (e.g. HIERARCHY_HIGHER, MODERATOR_MISSING_PERMISSION, NOT_BANNED, BOT_MISSING_PERMISSIONS)
requestedAtstring | 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)

錯誤

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),重試時沿用同一個值,變更就只會發生一次。 運作方式

請求內容

請求內容
欄位類型必填說明
reasonstring是Required. Shown in the case, the mod log and the member’s DM
1–500 個字元

回應

回應欄位 · 202
欄位類型必填說明
actionIdstring是
actionstring是其中之一 warn, timeout, untimeout, kick, ban, unban
userIdstring是
statusstring是其中之一 pending, running, done, failed
caseNumberinteger | null是
errorstring | null是Refusal code when failed (e.g. HIERARCHY_HIGHER, MODERATOR_MISSING_PERMISSION, NOT_BANNED, BOT_MISSING_PERMISSIONS)
requestedAtstring | 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)

錯誤

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),重試時沿用同一個值,變更就只會發生一次。 運作方式

請求內容

請求內容
欄位類型必填說明
reasonstring是Required. Shown in the case, the mod log and the member’s DM
1–500 個字元
evidencearray of string否Up to 5 links
最多 5 個項目

回應

回應欄位 · 202
欄位類型必填說明
actionIdstring是
actionstring是其中之一 warn, timeout, untimeout, kick, ban, unban
userIdstring是
statusstring是其中之一 pending, running, done, failed
caseNumberinteger | null是
errorstring | null是Refusal code when failed (e.g. HIERARCHY_HIGHER, MODERATOR_MISSING_PERMISSION, NOT_BANNED, BOT_MISSING_PERMISSIONS)
requestedAtstring | 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)

錯誤

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),重試時沿用同一個值,變更就只會發生一次。 運作方式

請求內容

請求內容
欄位類型必填說明
reasonstring是Required. Shown in the case, the mod log and the member’s DM
1–500 個字元
deleteMessageSecondsinteger否Delete the user’s messages of the last N seconds (≤ 7 days)
0–604,800
durationSecondsinteger | null否Temporary ban (≤ 365 days); omit for a permanent ban
60–31,536,000
evidencearray of string否Up to 5 links
最多 5 個項目

回應

回應欄位 · 202
欄位類型必填說明
actionIdstring是
actionstring是其中之一 warn, timeout, untimeout, kick, ban, unban
userIdstring是
statusstring是其中之一 pending, running, done, failed
caseNumberinteger | null是
errorstring | null是Refusal code when failed (e.g. HIERARCHY_HIGHER, MODERATOR_MISSING_PERMISSION, NOT_BANNED, BOT_MISSING_PERMISSIONS)
requestedAtstring | 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)

錯誤

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),重試時沿用同一個值,變更就只會發生一次。 運作方式

請求內容

請求內容
欄位類型必填說明
reasonstring是Required. Shown in the case, the mod log and the member’s DM
1–500 個字元

回應

回應欄位 · 202
欄位類型必填說明
actionIdstring是
actionstring是其中之一 warn, timeout, untimeout, kick, ban, unban
userIdstring是
statusstring是其中之一 pending, running, done, failed
caseNumberinteger | null是
errorstring | null是Refusal code when failed (e.g. HIERARCHY_HIGHER, MODERATOR_MISSING_PERMISSION, NOT_BANNED, BOT_MISSING_PERMISSIONS)
requestedAtstring | 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)

錯誤

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
欄位類型必填說明
actionIdstring是
actionstring是其中之一 warn, timeout, untimeout, kick, ban, unban
userIdstring是
statusstring是其中之一 pending, running, done, failed
caseNumberinteger | null是
errorstring | null是Refusal code when failed (e.g. HIERARCHY_HIGHER, MODERATOR_MISSING_PERMISSION, NOT_BANNED, BOT_MISSING_PERMISSIONS)
requestedAtstring | 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)

錯誤

準備好讓你的伺服器升級了嗎?

免費新增 BotGG,再到網頁控制台開啟需要的功能。