REST API v1 · 開發者 · API 參考

邀請與獎勵 API 參考

BotGG REST API v1 的所有 3 個 邀請與獎勵 端點:範圍、參數、欄位、錯誤,以及可直接執行的 curl、JavaScript 與 Python 範例。

開發者文件
本頁目錄

端點

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

邀請與獎勵 端點
端點範圍說明
GET/guilds/{guildId}/invites/members/{userId}invites:readGet a member’s invites
GET/guilds/{guildId}/invites/leaderboardinvites:readInvites leaderboard
POST/guilds/{guildId}/invites/members/{userId}/bonusinvites:writeAdd or remove bonus invites

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

Get a member’s invites

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

範圍: invites:read

Invite counters, all-time rank and the active season’s count and rank. Members who invited nobody get zeros.

需要在伺服器上啟用此功能: 邀請與獎勵

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

回應

回應欄位 · 200
欄位類型必填說明
userIdstring是
invitesinteger是verified + bonus (never below 0) — what milestones and the leaderboard use
verifiedinteger是
pendinginteger是
leftinteger是
fakeinteger是
bonusinteger是
totalinteger是
rankinteger | null是
seasonobject | null是The active season, if any
season.idinteger是
season.numberinteger是
season.namestring | null是
season.startsAtstring | null是
season.endsAtstring | null是
season.invitesinteger是
season.rankinteger | null是
回應 · 200
{
  "userId": "876543210987654321",
  "invites": 10,
  "verified": 10,
  "pending": 10,
  "left": 10,
  "fake": 10,
  "bonus": 10,
  "total": 10,
  "rank": 1,
  "season": {
    "id": 98765,
    "number": 7,
    "name": "Example",
    "startsAt": "2026-10-07T12:00:00.000Z",
    "endsAt": "2026-10-07T12:00:00.000Z",
    "invites": 10,
    "rank": 1
  }
}

範例

curl
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/invites/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/invites/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/invites/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)

錯誤

Invites leaderboard

GET/guilds/{guildId}/invites/leaderboard

範圍: invites:read

period=all ranks by invites (verified + bonus), period=season by the active season’s invites (empty without a season). Pass cursor=<nextCursor> for the next page.

需要在伺服器上啟用此功能: 邀請與獎勵

參數
名稱位置類型必填說明
guildId路徑string是你的伺服器 ID · Discord ID(字串)
period查詢字串string否其中之一 all, season · 預設值 "all"
limit查詢字串integer否1–100 · 預設值 25
cursor查詢字串integer否0–10,000,000 · 預設值 0

回應

回應欄位 · 200
欄位類型必填說明
periodstring是其中之一 all, season
seasonobject | null是
season.idinteger是
season.numberinteger是
season.namestring | null是
season.startsAtstring | null是
season.endsAtstring | null是
itemsarray of object是
items[].rankinteger是
items[].userIdstring是
items[].scoreinteger是
items[].invitesinteger是
items[].verifiedinteger是
items[].bonusinteger是
totalinteger是
nextCursorstring | null是
回應 · 200
{
  "period": "all",
  "season": {
    "id": 98765,
    "number": 7,
    "name": "Example",
    "startsAt": "2026-10-07T12:00:00.000Z",
    "endsAt": "2026-10-07T12:00:00.000Z"
  },
  "items": [
    {
      "rank": 1,
      "userId": "876543210987654321",
      "score": 10,
      "invites": 10,
      "verified": 10,
      "bonus": 10
    }
  ],
  "total": 10,
  "nextCursor": "98700"
}

範例

curl
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/invites/leaderboard?period=all&limit=25&cursor=0" \
  -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/invites/leaderboard?period=all&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);
Python (requests)
import os
import requests

res = requests.get(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/invites/leaderboard",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
    },
    params={
        "period": "all",
        "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)

錯誤

Add or remove bonus invites

POST/guilds/{guildId}/invites/members/{userId}/bonus

範圍: invites:writeIdempotency-Key

Same as /invites add|remove. Counts toward the active season; milestone rewards for additions are granted by the bot within a minute. Written to the audit log.

需要在伺服器上啟用此功能: 邀請與獎勵

參數
名稱位置類型必填說明
guildId路徑string是你的伺服器 ID · Discord ID(字串)
userId路徑string是成員的 Discord 使用者 ID · Discord ID(字串)
Idempotency-Key標頭string否選填。傳送一個唯一值(UUID),重試時沿用同一個值,變更就只會發生一次。 運作方式

請求內容

請求內容
欄位類型必填說明
amountinteger是Positive = add bonus invites, negative = remove
-100,000–100,000
reasonstring | null否Shown in the audit log
最多 200 個字元

回應

回應欄位 · 201
欄位類型必填說明
userIdstring是
amountinteger是
previousBonusinteger是
bonusinteger是
invitesinteger是
verifiedinteger是
回應 · 201
{
  "userId": "876543210987654321",
  "amount": 100,
  "previousBonus": 10,
  "bonus": 10,
  "invites": 10,
  "verified": 10
}

範例

curl
curl -s -X POST "https://console.botgg.app/api/v1/guilds/123456789012345678/invites/members/876543210987654321/bonus" \
  -H "Authorization: Bearer $BOTGG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"amount":100,"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/invites/members/876543210987654321/bonus', {
  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({
    amount: 100,
    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/invites/members/876543210987654321/bonus",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),  # reuse it when you retry this request
    },
    json={
        "amount": 100,
        "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,再到網頁控制台開啟需要的功能。