Bot API
For bots: show your server count, reward users who voted and get votes and reviews pushed to your own receiver. For servers: read your stats and reviews and see who bumped.
On this page
Introduction
The API uses JSON over HTTPS. All endpoints live under https://bumped.gg/api/v1. Discord ids are always sent and returned as strings, because they do not fit into a JavaScript number. Timestamps are RFC 3339 in UTC.
https://bumped.gg/api/v1Authentication
A bot can have up to 10 API tokens, each with a name and its own permissions: Read reads the bot and its reviews and checks votes, Write posts the server count. Open your bot, choose Edit listing, then API tokens under Integration. A token starts with bmp_ and is shown once. We only keep a hash, so a lost token has to be replaced: create a new one, then delete the old one.
Send it in the Authorization header, with or without a Bearer prefix. A token only works for the bot it was created for.
Authorization: bmp_9f2K…Keep tokens on your server. Anyone holding a token with write permission can change the server count shown on your page.
Quick start
Post the server count when the bot is ready and every 30 minutes after that.
// discord.js v14
import { Client, GatewayIntentBits } from "discord.js";
const client = new Client({ intents: [GatewayIntentBits.Guilds] });
async function postStats() {
const res = await fetch(`https://bumped.gg/api/v1/bots/${client.user.id}/stats`, {
method: "POST",
headers: { Authorization: process.env.BUMPED_TOKEN, "Content-Type": "application/json" },
body: JSON.stringify({ serverCount: client.guilds.cache.size }),
});
if (!res.ok) console.error("bumped", res.status, await res.text());
}
client.once("ready", () => {
postStats();
setInterval(postStats, 30 * 60 * 1000);
});
client.login(process.env.DISCORD_TOKEN);Endpoints
Post stats
/api/v1/bots/{botId}/statsUpdates the server count on your listing and its position in the “Most servers” sort. Until the first post, no count is shown at all. Sharded bots send the total across all shards.
Path
botIdstringrequired- Your application id.
Body
serverCountintegerrequired- Total servers the bot is in, 0 to 2147483647.
shardCountintegeroptional- Number of shards, 1 to 2147483647.
curl -X POST https://bumped.gg/api/v1/bots/1133835522113024151/stats \
-H "Authorization: $BUMPED_TOKEN" \
-H "Content-Type: application/json" \
-d '{"serverCount": 1650, "shardCount": 2}'Responses
- 204Saved. No body.
- 401Token missing, wrong, or created for another bot.
- 403The token has no write permission.
- 422A field is invalid.
fieldsnames it. - 429More than 10 posts per minute. Wait for Retry-After.
Get bot
/api/v1/bots/{botId}Your bot's listing state and counts, for example to show votes and rating in your own help or info command. Needs a token with read permission.
curl https://bumped.gg/api/v1/bots/1133835522113024151 \
-H "Authorization: $BUMPED_TOKEN"{
"id": "1133835522113024151",
"name": "Study Bot",
"status": "approved",
"listed": true,
"serverCount": 1650,
"shardCount": 2,
"statsUpdatedAt": "2026-11-12T18:02:11Z",
"monthlyVotes": 312,
"totalVotes": 4820,
"rating": { "average": 4.6, "count": 37 },
"categories": ["utility"],
"tags": ["study", "pomodoro"]
}Responses
- 200
listedis false until the bot is approved and while it is hidden.serverCount,shardCountandstatsUpdatedAtare null until you post stats. - 401Token missing, wrong, or created for another bot.
- 403The token has no read permission.
- 429More than 60 requests per minute.
Check a vote
/api/v1/bots/{botId}/check?userId={userId}Tells you whether a user voted for your bot in the last 12 hours, for example to unlock a reward command. If you handle many votes, use webhooks instead of polling this.
Query
userIdstringrequired- Discord user id to check.
curl "https://bumped.gg/api/v1/bots/1133835522113024151/check?userId=222333444555666777" \
-H "Authorization: $BUMPED_TOKEN"{
"voted": true,
"lastVoteAt": "2026-11-12T16:47:51Z"
}Responses
- 200
lastVoteAtis null when the user never voted. - 400userId is missing or not a number.
- 401Token missing, wrong, or created for another bot.
- 403The token has no read permission.
- 429More than 120 checks per minute.
List reviews
/api/v1/bots/{botId}/reviewsThe reviews shown on your bot's page, for example to quote them in your own bot or on your website. Reviews waiting for a moderator and removed ones are left out. To hear about new ones as they come in, use a review webhook. Needs a token with read permission.
Query
limitintegeroptional- 1 to 100, default 25.
offsetintegeroptional- How many reviews to skip, up to 10000. Default 0.
sortstringoptionalnew(default, newest first),helpful(most likes),highorlow(by stars).ratingintegeroptional- Only reviews with this many stars, 1 to 5.
curl "https://bumped.gg/api/v1/bots/1133835522113024151/reviews?limit=10" \
-H "Authorization: $BUMPED_TOKEN"{
"total": 37,
"rating": { "average": 4.6, "count": 37 },
"reviews": [
{
"id": "5120",
"rating": 5,
"body": "Reminders just work, and the setup took a minute.",
"likes": 3,
"createdAt": "2026-11-12T16:47:51Z",
"updatedAt": "2026-11-12T16:47:51Z",
"author": {
"id": "222333444555666777",
"username": "someone",
"displayName": "Display Name",
"avatar": "https://cdn.discordapp.com/avatars/222333444555666777/abc.png?size=256"
}
}
]
}Responses
- 200
totalcounts every review that matches,ratingcovers all reviews whatever the filter.updatedAtmoves when the author edits.avataris an empty string when the author has none. - 401Token missing, wrong, or created for another bot.
- 403The token has no read permission.
- 429More than 60 requests per minute.
Guild API
Listed servers get their own token, separate from bot tokens. Create it on the server's edit page under Guild API token. It can only read that one server. Names, icons and member counts come from Discord through our bot, so there is nothing to post.
Get server
/api/v1/servers/{serverId}Current listing state, counts and bump timing, for example to show “next bump in 40 minutes” in your own bot.
curl https://bumped.gg/api/v1/servers/1133835522113024151 \
-H "Authorization: $BUMPED_TOKEN"{
"id": "1133835522113024151",
"name": "Study Together",
"status": "listed",
"listed": true,
"memberCount": 1200,
"onlineCount": 310,
"statsUpdatedAt": "2026-11-12T18:02:11Z",
"bumpCount": 48,
"bumpedAt": "2026-11-12T17:19:42Z",
"nextBumpAt": "2026-11-12T19:19:42Z",
"tags": ["study", "productivity", "english"]
}Responses
- 200
listedis false for drafts, hidden servers, servers our bot left and servers whose invite stopped working.nextBumpAtis null when a bump is possible now. - 401Token missing, wrong, or created for another server.
- 429More than 60 requests per minute.
List bumps
/api/v1/servers/{serverId}/bumps?limit={limit}Who bumped and when, newest first. Use it to thank or reward bumpers in your server.
Query
limitintegeroptional- 1 to 100, default 25.
{
"bumps": [
{ "userId": "222333444555666777", "bumpedAt": "2026-11-12T17:19:42Z" }
]
}Responses
- 200An empty list when nobody has bumped yet.
- 401Token missing, wrong, or created for another server.
- 429More than 60 requests per minute, shared with Get server.
List reviews
/api/v1/servers/{serverId}/reviewsThe reviews shown on your server's page, written by members. Same query parameters and answer as for bots; reviews waiting for a moderator and removed ones are left out.
Query
limitintegeroptional- 1 to 100, default 25.
offsetintegeroptional- How many reviews to skip, up to 10000. Default 0.
sortstringoptionalnew(default, newest first),helpful(most likes),highorlow(by stars).ratingintegeroptional- Only reviews with this many stars, 1 to 5.
curl "https://bumped.gg/api/v1/servers/1133835522113024151/reviews?sort=helpful" \
-H "Authorization: $BUMPED_TOKEN"Responses
- 200The same body as List reviews for bots.
- 401Token missing, wrong, or created for another server.
- 429More than 60 requests per minute.
Webhooks
Set a receiver URL on your bot's edit page under Webhook and pick the events you want. We send a POST to it for each one. Discord channel webhooks cannot be used, because they would post the raw JSON into a channel. Webhooks are for bots only.
- The URL must be
https://and reachable from the internet. - We sign every request with a secret we create. If it leaks, generate a new one on the edit page.
- Send test vote on the edit page delivers a
webhook.testevent in the vote format, whatever events you picked.
Events
Every body has a type and a data object. Branch on type and ignore types you do not know, so new events never break your receiver. Webhooks created before events existed get votes only.
| Event on the edit page | type | Sent when |
|---|---|---|
| Votes | vote.create | Someone votes for your bot. |
| Reviews | review.create | A review appears on your page: a new one, or one a moderator approved. |
| review.update | The author edits a review that is already on your page. | |
| Always | webhook.test | You press Send test vote. |
Reviews that wait for a moderator are not sent until they are approved. Deleted and removed reviews send nothing. Treat data.id of a review as the key and store the latest version you received.
Vote payload
POST /your/path HTTP/1.1
Content-Type: application/json
User-Agent: bumped-webhooks/1
x-bumped-signature: t=1762966071,v1=5f1c0b…e9{
"type": "vote.create",
"data": {
"id": "1842",
"weight": 1,
"created_at": "2026-11-12T16:47:51Z",
"expires_at": "2026-11-13T04:47:51Z",
"user": {
"id": "222333444555666777",
"platform_id": "222333444555666777",
"name": "Display Name",
"avatar_url": "https://cdn.discordapp.com/avatars/222333444555666777/abc.png?size=256"
},
"project": {
"id": "1133835522113024151",
"type": "bot",
"platform": "discord",
"platform_id": "1133835522113024151"
}
}
}Fields
typestringrequiredvote.createfor a real vote,webhook.testfor the test button.data.idstringrequired- Unique per vote. Store it to ignore a retried delivery you already handled.
data.weightintegerrequired- Always 1 today.
data.created_atstringrequired- When the vote was cast.
data.expires_atstringrequired- When the user may vote again, 12 hours later.
data.user.platform_idstringrequired- The voter's Discord user id.
data.user.namestringrequired- Display name at the time of the vote.
data.user.avatar_urlstringrequired- Empty string when the user has no avatar.
data.project.platform_idstringrequired- Your application id.
Review payload
Headers and signature are the same as for votes.
{
"type": "review.create",
"data": {
"id": "5120",
"rating": 5,
"body": "Reminders just work, and the setup took a minute.",
"created_at": "2026-11-12T16:47:51Z",
"updated_at": "2026-11-12T16:47:51Z",
"user": {
"id": "222333444555666777",
"platform_id": "222333444555666777",
"name": "Display Name",
"avatar_url": "https://cdn.discordapp.com/avatars/222333444555666777/abc.png?size=256"
},
"project": {
"id": "1133835522113024151",
"type": "bot",
"platform": "discord",
"platform_id": "1133835522113024151"
}
}
}Fields
typestringrequiredreview.createorreview.update.data.idstringrequired- The review's id. One user has one review per bot, so an edit keeps the id.
data.ratingintegerrequired- 1 to 5 stars.
data.bodystringrequired- The review text, plain text.
data.created_atstringrequired- When the review was first written.
data.updated_atstringrequired- When it was last edited. Use it to drop an older update that arrives late.
data.user.platform_idstringrequired- The author's Discord user id.
data.user.namestringrequired- Display name at the time of sending.
data.project.platform_idstringrequired- Your application id.
Verify the signature
The x-bumped-signature header holds a Unix timestamp t and an HMAC-SHA256 v1, computed over <t>.<raw body> with your signing secret. Compare in constant time, use the raw body exactly as received, and reject timestamps older than five minutes so a captured request cannot be replayed.
import { createHmac, timingSafeEqual } from "node:crypto";
export function verify(header, rawBody, secret) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
const t = Number(parts.t);
if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
const given = Buffer.from(parts.v1 ?? "", "hex");
return given.length === 32 && timingSafeEqual(Buffer.from(expected, "hex"), given);
}Delivery and retries
Answer with any 2xx status within 10 seconds. Do slow work after you respond.
| Your answer | What we do |
|---|---|
| 2xx | Done. |
| 429, 5xx, timeout | Retry after 5 seconds, 30 seconds and 2 minutes, then give up. |
| other 4xx | No retry. Fix the receiver and send a test vote. |
| 3xx | Redirects are not followed and count as failed. |
We refuse receivers on private, loopback or link-local addresses, also when the hostname resolves to one.
Errors
Every error has a JSON body with a readable error message and a stable code to branch on; the message text may change, the code does not. Validation errors add fields and fieldCodes, rate limits add retryAfter in seconds and a matching Retry-After header.
{
"error": "Some fields need fixing.",
"code": "invalidFields",
"fields": { "serverCount": "Send a server count between 0 and 2147483647." },
"fieldCodes": { "serverCount": { "code": "serverCount", "params": { "max": 2147483647 } } }
}Responses
- 400The request is malformed, for example invalid JSON or a missing query parameter.
- 401Token missing, wrong, or created for another bot or server.
- 403The token lacks the permission this endpoint needs.
- 422The JSON is valid but a value is not.
- 429Rate limited. Wait for Retry-After.
- 500Our fault. Retry later; nothing was saved.
Rate limits
Limits count per bot or server in fixed one-minute windows. Only requests with a valid token count.
| Endpoint | Limit |
|---|---|
| POST /bots/{botId}/stats | 10 per minute |
| GET /bots/{botId} | 60 per minute |
| GET /bots/{botId}/check | 120 per minute |
| GET /bots/{botId}/reviews | 60 per minute |
| GET /servers/{serverId}, /bumps | 60 per minute, both endpoints together |
| GET /servers/{serverId}/reviews | 60 per minute |