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}/levels/members/{userId} | levels:read | Get a member’s level |
GET/guilds/{guildId}/levels/leaderboard | levels:read | XP leaderboard |
POST/guilds/{guildId}/levels/members/{userId}/xp-changes | levels:write | Add, remove or set a member’s XP |
GET/guilds/{guildId}/levels/xp-changes/{changeId} | levels:write | Get the status of an XP change |
除了下方各自的錯誤外,每個端點還可能回傳這些常見錯誤:
Get a member’s level
GET/guilds/{guildId}/levels/members/{userId}
Level, XP, progress and XP rank. Members without activity get zeros. Live activity can take a few seconds to show.
需要在伺服器上啟用此功能: 等級
| 名稱 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
guildId | 路徑 | string | 是 | 你的伺服器 ID · Discord ID(字串) |
userId | 路徑 | string | 是 | 成員的 Discord 使用者 ID · Discord ID(字串) |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
userId | string | 是 | |
xp | integer | 是 | |
level | integer | 是 | |
xpIntoLevel | integer | 是 | |
xpForNext | integer | 是 | |
progress | number | 是 | 0–1 inside the current level |
messages | integer | 是 | |
voiceMinutes | integer | 是 | |
streak | integer | 是 | |
bestStreak | integer | 是 | |
rank | integer | null | 是 | By XP; null without XP |
hidden | boolean | 是 | The member hid themselves from public leaderboards (/rank leaderboard:hide) |
lastXpAt | string | null | 是 |
{
"userId": "876543210987654321",
"xp": 150,
"level": 5,
"xpIntoLevel": 10,
"xpForNext": 10,
"progress": 10,
"messages": 10,
"voiceMinutes": 10,
"streak": 10,
"bestStreak": 10,
"rank": 1,
"hidden": true,
"lastXpAt": "2026-10-07T12:00:00.000Z"
}範例
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/levels/members/876543210987654321" \
-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/levels/members/876543210987654321', {
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/levels/members/876543210987654321",
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 | 代碼 |
|---|---|
| 409 | FEATURE_DISABLED |
| 503 | SERVICE_UNAVAILABLE |
XP leaderboard
GET/guilds/{guildId}/levels/leaderboard
Highest XP first. Pass cursor=<nextCursor> for the next page. Members who hid themselves from public leaderboards keep their rank but have userId: null — respect that if you publish the list.
需要在伺服器上啟用此功能: 等級
| 名稱 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
guildId | 路徑 | string | 是 | 你的伺服器 ID · Discord ID(字串) |
limit | 查詢字串 | integer | 否 | 1–100 · 預設值 25 |
cursor | 查詢字串 | integer | 否 | 0–10,000,000 · 預設值 0 |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
items | array of object | 是 | |
items[].rank | integer | 是 | |
items[].userId | string | null | 是 | null for members who hid themselves from public leaderboards |
items[].hidden | boolean | 是 | |
items[].xp | integer | 是 | |
items[].level | integer | 是 | |
items[].messages | integer | 是 | |
items[].voiceMinutes | integer | 是 | |
total | integer | 是 | |
nextCursor | string | null | 是 |
{
"items": [
{
"rank": 1,
"userId": "876543210987654321",
"hidden": true,
"xp": 150,
"level": 5,
"messages": 10,
"voiceMinutes": 10
}
],
"total": 10,
"nextCursor": "98700"
}範例
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/levels/leaderboard?limit=25&cursor=0" \
-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/levels/leaderboard?limit=25&cursor=0', {
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/levels/leaderboard",
headers={
"Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
},
params={
"limit": 25,
"cursor": 0,
},
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 |
Add, remove or set a member’s XP
POST/guilds/{guildId}/levels/members/{userId}/xp-changes
Same as /levels give|take|set: the bot applies the change within a few seconds, then updates reward roles and posts level-up announcements. Answers 202 with a change id — poll GET …/levels/xp-changes/{changeId} for the result. Written to the audit log.
需要在伺服器上啟用此功能: 等級
| 名稱 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
guildId | 路徑 | string | 是 | 你的伺服器 ID · Discord ID(字串) |
userId | 路徑 | string | 是 | 成員的 Discord 使用者 ID · Discord ID(字串) |
Idempotency-Key | 標頭 | string | 否 | 選填。傳送一個唯一值(UUID),重試時沿用同一個值,變更就只會發生一次。 運作方式 |
請求內容
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
type | string | 是 | add / remove = relative change, set = new total 其中之一 add, remove, set |
amount | integer | 是 | 0–2,000,000,000 |
unit | string | 否 | Default xp. With levels, the progress inside the level is kept其中之一 xp, levels |
reason | string | null | 否 | Shown in the audit log 最多 200 個字元 |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
changeId | string | 是 | |
userId | string | 是 | |
type | string | 是 | 其中之一 add, remove, set |
unit | string | 是 | 其中之一 xp, levels |
amount | integer | 是 | |
status | string | 是 | 其中之一 pending, processing, done, failed |
result | object | null | 是 | When done |
result.previousLevel | integer | 是 | |
result.level | integer | 是 | |
result.xp | integer | 是 | |
error | string | null | 是 | When failed |
createdAt | string | 是 | |
processedAt | string | null | 是 |
{
"changeId": "234567890123456789",
"userId": "876543210987654321",
"type": "add",
"unit": "xp",
"amount": 100,
"status": "pending",
"result": {
"previousLevel": 4,
"level": 5,
"xp": 150
},
"error": "example",
"createdAt": "2026-10-07T12:00:00.000Z",
"processedAt": "2026-10-07T12:00:00.000Z"
}範例
curl -s -X POST "https://console.botgg.app/api/v1/guilds/123456789012345678/levels/members/876543210987654321/xp-changes" \
-H "Authorization: Bearer $BOTGG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"type":"add","amount":100,"unit":"xp","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/levels/members/876543210987654321/xp-changes', {
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({
type: 'add',
amount: 100,
unit: 'xp',
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/levels/members/876543210987654321/xp-changes",
headers={
"Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()), # reuse it when you retry this request
},
json={
"type": "add",
"amount": 100,
"unit": "xp",
"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 status of an XP change
GET/guilds/{guildId}/levels/xp-changes/{changeId}
Only changes made with the same API key. done includes the level before/after and the new XP total.
需要在伺服器上啟用此功能: 等級
| 名稱 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
guildId | 路徑 | string | 是 | 你的伺服器 ID · Discord ID(字串) |
changeId | 路徑 | string | 是 |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
changeId | string | 是 | |
userId | string | 是 | |
type | string | 是 | 其中之一 add, remove, set |
unit | string | 是 | 其中之一 xp, levels |
amount | integer | 是 | |
status | string | 是 | 其中之一 pending, processing, done, failed |
result | object | null | 是 | When done |
result.previousLevel | integer | 是 | |
result.level | integer | 是 | |
result.xp | integer | 是 | |
error | string | null | 是 | When failed |
createdAt | string | 是 | |
processedAt | string | null | 是 |
{
"changeId": "234567890123456789",
"userId": "876543210987654321",
"type": "add",
"unit": "xp",
"amount": 100,
"status": "pending",
"result": {
"previousLevel": 4,
"level": 5,
"xp": 150
},
"error": "example",
"createdAt": "2026-10-07T12:00:00.000Z",
"processedAt": "2026-10-07T12:00:00.000Z"
}範例
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/levels/xp-changes/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/levels/xp-changes/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/levels/xp-changes/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 | XP_CHANGE_NOT_FOUND |
| 409 | FEATURE_DISABLED |
| 503 | SERVICE_UNAVAILABLE |