Zum Inhalt springen

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.

Base URL
https://bumped.gg/api/v1

Authentication

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.

Header
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

POST/api/v1/bots/{botId}/stats

Updates 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. fields names it.
  • 429More than 10 posts per minute. Wait for Retry-After.

Get bot

GET/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"
200 OK
{
  "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

  • 200listed is false until the bot is approved and while it is hidden. serverCount, shardCount and statsUpdatedAt are 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

GET/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"
200 OK
{
  "voted": true,
  "lastVoteAt": "2026-11-12T16:47:51Z"
}

Responses

  • 200lastVoteAt is 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

GET/api/v1/bots/{botId}/reviews

The 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.
sortstringoptional
new (default, newest first), helpful (most likes), high or low (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"
200 OK
{
  "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

  • 200total counts every review that matches, rating covers all reviews whatever the filter. updatedAt moves when the author edits. avatar is 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

GET/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"
200 OK
{
  "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

  • 200listed is false for drafts, hidden servers, servers our bot left and servers whose invite stopped working. nextBumpAt is null when a bump is possible now.
  • 401Token missing, wrong, or created for another server.
  • 429More than 60 requests per minute.

List bumps

GET/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.
200 OK
{
  "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

GET/api/v1/servers/{serverId}/reviews

The 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.
sortstringoptional
new (default, newest first), helpful (most likes), high or low (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.test event 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 pagetypeSent when
Votesvote.createSomeone votes for your bot.
Reviewsreview.createA review appears on your page: a new one, or one a moderator approved.
review.updateThe author edits a review that is already on your page.
Alwayswebhook.testYou 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

Request
POST /your/path HTTP/1.1
Content-Type: application/json
User-Agent: bumped-webhooks/1
x-bumped-signature: t=1762966071,v1=5f1c0b…e9
Body
{
  "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

typestringrequired
vote.create for a real vote, webhook.test for 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.

Body
{
  "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

typestringrequired
review.create or review.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 answerWhat we do
2xxDone.
429, 5xx, timeoutRetry after 5 seconds, 30 seconds and 2 minutes, then give up.
other 4xxNo retry. Fix the receiver and send a test vote.
3xxRedirects 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.

422 Unprocessable Entity
{
  "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.

EndpointLimit
POST /bots/{botId}/stats10 per minute
GET /bots/{botId}60 per minute
GET /bots/{botId}/check120 per minute
GET /bots/{botId}/reviews60 per minute
GET /servers/{serverId}, /bumps60 per minute, both endpoints together
GET /servers/{serverId}/reviews60 per minute