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}/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 |
除了下方各自的錯誤外,每個端點還可能回傳這些常見錯誤:
List ban appeals
GET/guilds/{guildId}/appeals
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 |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
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 | 是 |
{
"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 -s "https://console.botgg.app/api/v1/guilds/123456789012345678/appeals?status=open&limit=25" \
-H "Authorization: Bearer $BOTGG_API_KEY"// 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);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}
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 | 是 |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
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 | 是 |
{
"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 -s "https://console.botgg.app/api/v1/guilds/123456789012345678/appeals/234567890123456789" \
-H "Authorization: Bearer $BOTGG_API_KEY"// 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);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
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 個字元 |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
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 | 是 |
{
"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 -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"}'// 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);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
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 個字元 |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
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 | 是 |
{
"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 -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"}'// 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);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)