API Documentation

The MonkeyBytes List API lets your bot post server counts and receive vote events. Authenticate with the API token found in your bot's dashboard.

Post bot stats

Update your server & shard counts. Call this periodically (e.g. every 30 min).

POST /api/bots/:id/stats
Authorization: Bearer <YOUR_API_TOKEN>
Content-Type: application/json

{
  "serverCount": 1234,
  "shardCount": 4
}

Get a bot

GET /api/bots/:id

{
  "id": "...",
  "name": "BananaBot",
  "serverCount": 1234,
  "monthlyVotes": 842,
  "totalVotes": 15203,
  "certified": true
}

Check a user's vote

GET /api/bots/:id/check?userId=<DISCORD_USER_ID>
Authorization: Bearer <YOUR_API_TOKEN>

{ "voted": true }

Vote webhooks

Set a webhook URL in your dashboard to receive a POST every time someone votes. The payload is top.gg-compatible:

POST <your webhook url>
Authorization: <your webhook secret>
X-Signature: <hmac-sha256 of the body using your secret>

{
  "id": "uuid",
  "bot": "<bot client id>",
  "user": "<voter discord id>",
  "type": "upvote",
  "isWeekend": false,
  "timestamp": "2026-01-01T00:00:00.000Z"
}

Widgets

Embed a live vote-count badge anywhere:

<img src="https://blubird.qzz.io/api/widget/bot/:id" alt="votes" />

Rate limits

Public endpoints are limited to 60 requests/minute per IP. Stats posts: 30/minute per token.