API Documentation

With the MicupList API you can post your bot's server count, check whether users voted and receive vote webhooks.

Authentication

Create an API token on your bot's dashboard page and send it in the Authorization header of every request.

Authorization: ml_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Base URL:

https://micuplist.me/api/v1

Rate limits: 60 requests per minute per IP; stats posting is limited to 2 requests per minute per bot.

Endpoints

POST/bots/{id}/statsToken required

Updates your bot's server (and optional shard) count.

{ "serverCount": 1250, "shardCount": 2 }

GET/bots/{id}/check?userId={userId}Token required

Returns whether the user voted within the cooldown window.

{ "voted": true }

GET/bots/{id}/votesToken required

Returns the latest 100 votes for your bot.

GET/bots/{id}

Returns public information about an approved bot.

GET/servers/{id}

Returns public information about an approved server.

Vote webhook

If you set a webhook URL in your dashboard, a POST request like the one below is sent on every vote. Verify it by comparing the Authorization header with your webhook secret. Failed deliveries are retried 3 times.

POST https://your-bot.example.com/micuplist
Authorization: <webhook secret>
Content-Type: application/json

{
  "type": "vote",            // "test" when sent from the dashboard
  "botId": "1564535472599334913",
  "userId": "1559444666317799424",
  "isWeekend": false,
  "timestamp": "2026-10-27T12:00:00.000Z"
}

Examples

JavaScript

const TOKEN = process.env.MICUPLIST_TOKEN;
const BOT_ID = '<your bot id>';

// Post server count every 30 minutes
setInterval(async () => {
  await fetch('https://micuplist.me/api/v1/bots/' + BOT_ID + '/stats', {
    method: 'POST',
    headers: { Authorization: TOKEN, 'Content-Type': 'application/json' },
    body: JSON.stringify({ serverCount: client.guilds.cache.size }),
  });
}, 30 * 60 * 1000);

// Check whether a user voted
const res = await fetch('https://micuplist.me/api/v1/bots/' + BOT_ID + '/check?userId=' + userId, {
  headers: { Authorization: TOKEN },
});
const { voted } = await res.json();

Python

import os, requests

TOKEN = os.environ["MICUPLIST_TOKEN"]
BOT_ID = "<your bot id>"

requests.post(
    f"https://micuplist.me/api/v1/bots/{BOT_ID}/stats",
    headers={"Authorization": TOKEN},
    json={"serverCount": 1250},
    timeout=10,
)

Errors

Errors are returned with an appropriate HTTP status code in the following format.

{ "error": "RATE_LIMITED", "resetAt": "2026-10-27T12:01:00.000Z" }