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} | guild:read | Get the server |
GET/guilds/{guildId}/roles | guild:read | List roles |
GET/guilds/{guildId}/channels | guild:read | List channels |
GET/guilds/{guildId}/members/{userId} | guild:read | Get a member |
除了下方各自的錯誤外,每個端點還可能回傳這些常見錯誤:
Get the server
GET/guilds/{guildId}
Name, icon, approximate member count, the bot’s language and the enabled BotGG features.
| 名稱 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
guildId | 路徑 | string | 是 | 你的伺服器 ID · Discord ID(字串) |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
id | string | 是 | |
name | string | 是 | |
icon | string | null | 是 | |
iconUrl | string | null | 是 | |
memberCount | integer | null | 是 | Approximate; null when Discord is unreachable |
locale | string | 是 | The bot’s language on this server (en, ru, he, zh-TW) |
enabledFeatures | array of string | 是 |
{
"id": "example",
"name": "Example",
"icon": "example",
"iconUrl": "https://example.com",
"memberCount": 10,
"locale": "example",
"enabledFeatures": [
"example"
]
}範例
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678" \
-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', {
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",
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)錯誤
只會出現「端點」下列出的常見錯誤。
List roles
GET/guilds/{guildId}/roles
Highest first (Discord order), without @everyone.
| 名稱 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
guildId | 路徑 | string | 是 | 你的伺服器 ID · Discord ID(字串) |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
items | array of object | 是 | |
items[].id | string | 是 | |
items[].name | string | 是 | |
items[].color | string | null | 是 | |
items[].position | integer | 是 | |
items[].managed | boolean | 是 | |
items[].hoist | boolean | 是 | |
items[].mentionable | boolean | 是 |
{
"items": [
{
"id": "example",
"name": "Example",
"color": "#18d7ff",
"position": 10,
"managed": true,
"hoist": true,
"mentionable": true
}
]
}範例
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/roles" \
-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/roles', {
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/roles",
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 | 代碼 |
|---|---|
| 503 | SERVICE_UNAVAILABLE |
List channels
GET/guilds/{guildId}/channels
In Discord’s sidebar order (categories followed by their channels); threads are not included.
| 名稱 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
guildId | 路徑 | string | 是 | 你的伺服器 ID · Discord ID(字串) |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
items | array of object | 是 | |
items[].id | string | 是 | |
items[].name | string | 是 | |
items[].type | string | 是 | 其中之一 text, voice, category, announcement, stage, forum, media, other |
items[].parentId | string | null | 是 | |
items[].position | integer | 是 |
{
"items": [
{
"id": "example",
"name": "Example",
"type": "text",
"parentId": "234567890123456789",
"position": 10
}
]
}範例
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/channels" \
-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/channels', {
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/channels",
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 | 代碼 |
|---|---|
| 503 | SERVICE_UNAVAILABLE |
Get a member
GET/guilds/{guildId}/members/{userId}
Basic member info: names, avatar, role ids and join date. Cached for up to 5 minutes.
| 名稱 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
guildId | 路徑 | string | 是 | 你的伺服器 ID · Discord ID(字串) |
userId | 路徑 | string | 是 | 成員的 Discord 使用者 ID · Discord ID(字串) |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
userId | string | 是 | |
username | string | null | 是 | |
globalName | string | null | 是 | |
nickname | string | null | 是 | |
displayName | string | null | 是 | |
avatarUrl | string | null | 是 | |
bot | boolean | 是 | |
roles | array of string | 是 | Role ids |
joinedAt | string | null | 是 |
{
"userId": "876543210987654321",
"username": "example",
"globalName": "example",
"nickname": "example",
"displayName": "example",
"avatarUrl": "https://example.com",
"bot": false,
"roles": [
"example"
],
"joinedAt": "2026-10-07T12:00:00.000Z"
}範例
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/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/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/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 | 代碼 |
|---|---|
| 404 | MEMBER_NOT_FOUND |
| 503 | SERVICE_UNAVAILABLE |