BotGG
EN
Open console Add to Discord

REST API v1 · Developers · API reference

Levels API reference

All 4 Levels endpoints of the BotGG REST API v1: scopes, parameters, fields, errors and ready-to-run curl, JavaScript and Python examples.

Updated: OpenAPI 3.1 (JSON)

Developer docs
On this page

Endpoints

Paths are relative to https://console.botgg.app/api/v1. Send your API key as Authorization: Bearer botgg_…; IDs are strings.

Levels endpoints
EndpointScopeDescription
GET/guilds/{guildId}/levels/members/{userId}levels:readGet a member’s level
GET/guilds/{guildId}/levels/leaderboardlevels:readXP leaderboard
POST/guilds/{guildId}/levels/members/{userId}/xp-changeslevels:writeAdd, remove or set a member’s XP
GET/guilds/{guildId}/levels/xp-changes/{changeId}levels:writeGet the status of an XP change

Besides its own errors below, every endpoint can return these common ones:

Errors
HTTPCodes
400INVALID_REQUEST
401UNAUTHORIZED, INVALID_API_KEY, API_KEY_REVOKED, API_KEY_EXPIRED
403BROWSER_REQUESTS_NOT_ALLOWED, GUILD_MISMATCH, INSUFFICIENT_SCOPE, GUILD_BLOCKED
404BOT_NOT_IN_GUILD
429RATE_LIMITED
500INTERNAL

Get a member’s level

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

Scope: levels:read

Level, XP, progress and XP rank. Members without activity get zeros. Live activity can take a few seconds to show.

Needs this feature enabled on the server: Levels

Parameters
NameInTypeRequiredDescription
guildIdpathstringYesYour server’s ID · Discord ID (string)
userIdpathstringYesThe member’s Discord user ID · Discord ID (string)

Response

Response fields · 200
FieldTypeRequiredDescription
userIdstringYes
xpintegerYes
levelintegerYes
xpIntoLevelintegerYes
xpForNextintegerYes
progressnumberYes0–1 inside the current level
messagesintegerYes
voiceMinutesintegerYes
streakintegerYes
bestStreakintegerYes
rankinteger | nullYesBy XP; null without XP
hiddenbooleanYesThe member hid themselves from public leaderboards (/rank leaderboard:hide)
lastXpAtstring | nullYes
Response · 200
{
  "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"
}

Examples

curl
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/levels/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/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);
Python (requests)
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)

Errors

Errors
HTTPCodes
409FEATURE_DISABLED
503SERVICE_UNAVAILABLE

XP leaderboard

GET/guilds/{guildId}/levels/leaderboard

Scope: levels:read

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.

Needs this feature enabled on the server: Levels

Parameters
NameInTypeRequiredDescription
guildIdpathstringYesYour server’s ID · Discord ID (string)
limitqueryintegerNo1–100 · Default 25
cursorqueryintegerNo0–10,000,000 · Default 0

Response

Response fields · 200
FieldTypeRequiredDescription
itemsarray of objectYes
items[].rankintegerYes
items[].userIdstring | nullYesnull for members who hid themselves from public leaderboards
items[].hiddenbooleanYes
items[].xpintegerYes
items[].levelintegerYes
items[].messagesintegerYes
items[].voiceMinutesintegerYes
totalintegerYes
nextCursorstring | nullYes
Response · 200
{
  "items": [
    {
      "rank": 1,
      "userId": "876543210987654321",
      "hidden": true,
      "xp": 150,
      "level": 5,
      "messages": 10,
      "voiceMinutes": 10
    }
  ],
  "total": 10,
  "nextCursor": "98700"
}

Examples

curl
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/levels/leaderboard?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/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);
Python (requests)
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)

Errors

Errors
HTTPCodes
409FEATURE_DISABLED
503SERVICE_UNAVAILABLE

Add, remove or set a member’s XP

POST/guilds/{guildId}/levels/members/{userId}/xp-changes

Scope: levels:writeIdempotency-Key

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.

Needs this feature enabled on the server: Levels

Parameters
NameInTypeRequiredDescription
guildIdpathstringYesYour server’s ID · Discord ID (string)
userIdpathstringYesThe member’s Discord user ID · Discord ID (string)
Idempotency-KeyheaderstringNoOptional. Send a unique value (a UUID) and reuse it when you retry: the change happens only once. How it works

Request body

Request body
FieldTypeRequiredDescription
typestringYesadd / remove = relative change, set = new total
One of add, remove, set
amountintegerYes0–2,000,000,000
unitstringNoDefault xp. With levels, the progress inside the level is kept
One of xp, levels
reasonstring | nullNoShown in the audit log
up to 200 characters

Response

Response fields · 202
FieldTypeRequiredDescription
changeIdstringYes
userIdstringYes
typestringYesOne of add, remove, set
unitstringYesOne of xp, levels
amountintegerYes
statusstringYesOne of pending, processing, done, failed
resultobject | nullYesWhen done
result.previousLevelintegerYes
result.levelintegerYes
result.xpintegerYes
errorstring | nullYesWhen failed
createdAtstringYes
processedAtstring | nullYes
Response · 202
{
  "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"
}

Examples

curl
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"}'
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/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);
Python (requests)
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)

Errors

Errors
HTTPCodes
400INVALID_JSON
404MEMBER_NOT_FOUND
409FEATURE_DISABLED
413PAYLOAD_TOO_LARGE
415UNSUPPORTED_MEDIA_TYPE
422IDEMPOTENCY_KEY_REUSED, BOT_ACCOUNT
503SERVICE_UNAVAILABLE

Get the status of an XP change

GET/guilds/{guildId}/levels/xp-changes/{changeId}

Scope: levels:write

Only changes made with the same API key. done includes the level before/after and the new XP total.

Needs this feature enabled on the server: Levels

Parameters
NameInTypeRequiredDescription
guildIdpathstringYesYour server’s ID · Discord ID (string)
changeIdpathstringYes

Response

Response fields · 200
FieldTypeRequiredDescription
changeIdstringYes
userIdstringYes
typestringYesOne of add, remove, set
unitstringYesOne of xp, levels
amountintegerYes
statusstringYesOne of pending, processing, done, failed
resultobject | nullYesWhen done
result.previousLevelintegerYes
result.levelintegerYes
result.xpintegerYes
errorstring | nullYesWhen failed
createdAtstringYes
processedAtstring | nullYes
Response · 200
{
  "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"
}

Examples

curl
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/levels/xp-changes/234567890123456789" \
  -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/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);
Python (requests)
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)

Errors

Errors
HTTPCodes
404XP_CHANGE_NOT_FOUND
409FEATURE_DISABLED
503SERVICE_UNAVAILABLE

Ready to level up your server?

Add BotGG for free, then switch features on in the web console.

Add to DiscordOpen the console