REST API v1 · 開發者 · API 參考

停權申訴 API 參考

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

開發者文件
本頁目錄

端點

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

停權申訴 端點
端點範圍說明
GET/guilds/{guildId}/appealsappeals:readList ban appeals
GET/guilds/{guildId}/appeals/{number}appeals:readGet a ban appeal
POST/guilds/{guildId}/appeals/{number}/approveappeals:writeApprove a ban appeal (unban)
POST/guilds/{guildId}/appeals/{number}/rejectappeals:writeReject a ban appeal

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

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查詢字串string否其中之一 open, question, approved, rejected, closed, all · 預設值 "open"
userId查詢字串string否Only this user’s appeals
Discord ID(字串)
limit查詢字串integer否1–100 · 預設值 25
before查詢字串integer否1–999,999,999

回應

回應欄位 · 200
欄位類型必填說明
itemsarray of object是
items[].numberinteger是
items[].userIdstring是
items[].userTagstring | null是
items[].statusstring是其中之一 open, question, approved, rejected, closed
items[].banCaseNumberinteger | null是
items[].claimedBystring | null是
items[].decidedBystring | null是null = system / API
items[].decidedAtstring | null是ISO 8601 date-time
items[].reasonstring | null是
items[].createdAtstring | null是ISO 8601 date-time
items[].lastActivityAtstring | null是ISO 8601 date-time
nextCursorstring | 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)

錯誤

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
欄位類型必填說明
numberinteger是
userIdstring是
userTagstring | null是
statusstring是其中之一 open, question, approved, rejected, closed
banCaseNumberinteger | null是
claimedBystring | null是
decidedBystring | null是null = system / API
decidedAtstring | null是ISO 8601 date-time
reasonstring | null是
createdAtstring | null是ISO 8601 date-time
lastActivityAtstring | null是ISO 8601 date-time
banReasonstring | null是
answersarray of object是
answers[].idstring是
answers[].typestring是
answers[].labelstring是
answers[].valueany是
messagesarray of object是The conversation the appellant sees (staff questions + replies). Internal notes are never included.
messages[].authorstring是其中之一 user, staff
messages[].authorIdstring | null是
messages[].textstring是
messages[].createdAtstring | null是ISO 8601 date-time
applyingboolean是A console/API decision is still being applied in Discord
failedActionobject | null是
failedAction.typestring是
failedAction.errorstring | 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)

錯誤

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

請求內容

請求內容
欄位類型必填說明
reasonstring | null否Sent to the appellant (DM / appeal page)
最多 1,000 個字元

回應

回應欄位 · 202
欄位類型必填說明
numberinteger是
userIdstring是
userTagstring | null是
statusstring是其中之一 open, question, approved, rejected, closed
banCaseNumberinteger | null是
claimedBystring | null是
decidedBystring | null是null = system / API
decidedAtstring | null是ISO 8601 date-time
reasonstring | null是
createdAtstring | null是ISO 8601 date-time
lastActivityAtstring | null是ISO 8601 date-time
banReasonstring | null是
answersarray of object是
answers[].idstring是
answers[].typestring是
answers[].labelstring是
answers[].valueany是
messagesarray of object是The conversation the appellant sees (staff questions + replies). Internal notes are never included.
messages[].authorstring是其中之一 user, staff
messages[].authorIdstring | null是
messages[].textstring是
messages[].createdAtstring | null是ISO 8601 date-time
applyingboolean是A console/API decision is still being applied in Discord
failedActionobject | null是
failedAction.typestring是
failedAction.errorstring | 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)

錯誤

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

請求內容

請求內容
欄位類型必填說明
reasonstring | null否Sent to the appellant (DM / appeal page)
最多 1,000 個字元

回應

回應欄位 · 202
欄位類型必填說明
numberinteger是
userIdstring是
userTagstring | null是
statusstring是其中之一 open, question, approved, rejected, closed
banCaseNumberinteger | null是
claimedBystring | null是
decidedBystring | null是null = system / API
decidedAtstring | null是ISO 8601 date-time
reasonstring | null是
createdAtstring | null是ISO 8601 date-time
lastActivityAtstring | null是ISO 8601 date-time
banReasonstring | null是
answersarray of object是
answers[].idstring是
answers[].typestring是
answers[].labelstring是
answers[].valueany是
messagesarray of object是The conversation the appellant sees (staff questions + replies). Internal notes are never included.
messages[].authorstring是其中之一 user, staff
messages[].authorIdstring | null是
messages[].textstring是
messages[].createdAtstring | null是ISO 8601 date-time
applyingboolean是A console/API decision is still being applied in Discord
failedActionobject | null是
failedAction.typestring是
failedAction.errorstring | 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)

錯誤

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

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