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:readGet the server
GET/guilds/{guildId}/rolesguild:readList roles
GET/guilds/{guildId}/channelsguild:readList channels
GET/guilds/{guildId}/members/{userId}guild:readGet a member

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

Get the server

GET/guilds/{guildId}

範圍: guild:read

Name, icon, approximate member count, the bot’s language and the enabled BotGG features.

參數
名稱位置類型必填說明
guildId路徑string是你的伺服器 ID · Discord ID(字串)

回應

回應欄位 · 200
欄位類型必填說明
idstring是
namestring是
iconstring | null是
iconUrlstring | null是
memberCountinteger | null是Approximate; null when Discord is unreachable
localestring是The bot’s language on this server (en, ru, he, zh-TW)
enabledFeaturesarray of string是
回應 · 200
{
  "id": "example",
  "name": "Example",
  "icon": "example",
  "iconUrl": "https://example.com",
  "memberCount": 10,
  "locale": "example",
  "enabledFeatures": [
    "example"
  ]
}

範例

curl
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678" \
  -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', {
  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",
    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

範圍: guild:read

Highest first (Discord order), without @everyone.

參數
名稱位置類型必填說明
guildId路徑string是你的伺服器 ID · Discord ID(字串)

回應

回應欄位 · 200
欄位類型必填說明
itemsarray of object是
items[].idstring是
items[].namestring是
items[].colorstring | null是
items[].positioninteger是
items[].managedboolean是
items[].hoistboolean是
items[].mentionableboolean是
回應 · 200
{
  "items": [
    {
      "id": "example",
      "name": "Example",
      "color": "#18d7ff",
      "position": 10,
      "managed": true,
      "hoist": true,
      "mentionable": true
    }
  ]
}

範例

curl
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/roles" \
  -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/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);
Python (requests)
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代碼
503SERVICE_UNAVAILABLE

List channels

GET/guilds/{guildId}/channels

範圍: guild:read

In Discord’s sidebar order (categories followed by their channels); threads are not included.

參數
名稱位置類型必填說明
guildId路徑string是你的伺服器 ID · Discord ID(字串)

回應

回應欄位 · 200
欄位類型必填說明
itemsarray of object是
items[].idstring是
items[].namestring是
items[].typestring是其中之一 text, voice, category, announcement, stage, forum, media, other
items[].parentIdstring | null是
items[].positioninteger是
回應 · 200
{
  "items": [
    {
      "id": "example",
      "name": "Example",
      "type": "text",
      "parentId": "234567890123456789",
      "position": 10
    }
  ]
}

範例

curl
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/channels" \
  -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/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);
Python (requests)
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代碼
503SERVICE_UNAVAILABLE

Get a member

GET/guilds/{guildId}/members/{userId}

範圍: guild:read

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(字串)

回應

回應欄位 · 200
欄位類型必填說明
userIdstring是
usernamestring | null是
globalNamestring | null是
nicknamestring | null是
displayNamestring | null是
avatarUrlstring | null是
botboolean是
rolesarray of string是Role ids
joinedAtstring | null是
回應 · 200
{
  "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
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/members/876543210987654321" \
  -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/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);
Python (requests)
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)

錯誤

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

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