Discord Bot List API

Post your server count, publish your commands, and check whether somebody voted — in about five minutes.

Five endpoints, one token. Everything here is HTTP and JSON, and the field names deliberately match what the other bot lists use, so a library that already posts to several of them can add this one as configuration rather than as code.

There is also an official client for JavaScript and Python if you would rather not write the autoposter, the retry and the webhook signature check yourself.

Post your server count

One POST on a timer. The number appears on your page and in every listing row.

Check a vote

The endpoint behind vote-for-perks. 600 requests a minute, per bot.

Receive vote webhooks

We POST to your URL when somebody votes. Signed, and retried five times.

Publish your commands

Forward what you registered with Discord. Your page stops going stale.

Get a token

1. List your bot

   Submit it with its Discord application id. Approval is manual and usually same-day.

2. Open its edit page

   https://discordbotlist.lol/bot/<your-bot-id>/edit, under API token.

3. Generate the token

   It is shown once. Store it the way you store your Discord token — in the environment, not in the repository. Losing it means generating a new one, which invalidates the old immediately.

A token acts on exactly one listing. It cannot read or write another bot, and asking about one answers 404 rather than 403 — so a leaked token cannot be used to find out which other bots exist.

Your first request

cURL

curl -X POST https://discordbotlist.lol/api/v1/bots/YOUR_BOT_ID/stats \
  -H "Authorization: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"server_count": 1482}'

Response

{ "success": true, "server_count": 1482 }

What each endpoint costs you

Rate limits are per token, per minute, and they are sized for what the endpoint is actually for rather than set to one number for tidiness.

Endpoint	Method	Limit	Why that number
/stats	POST	60/min	A sharded bot posts once per shard.
/commands	PUT	10/min	Published on startup, so it only has to clear a restart loop.
/check	GET	600/min	Called once per command invocation in a busy bot.
/votes	GET	60/min	A log you poll, not a hot path.
/widget	GET	none	Public, unauthenticated, cached 5 minutes.

A 429 carries retryAfter in seconds. Back off on it rather than retrying immediately — the limiter is per token, so a tight retry loop only spends your own budget.

If our Redis is down the limiter fails open, not closed. A cache outage must not stop a running bot from posting its count; the token still has to be valid either way.