API Documentation

The RankCore API lets bot developers post their server count, check whether a user has voted and receive vote events in real time. It is compatible in shape with the top.gg v0 API, so most existing libraries work by changing the base URL.

Base URL: https://rankcore.org/api · All responses are JSON.

Authentication

Get your token from your bot page → Webhooks & API. Send it in the Authorization header:

Authorization: YOUR_TOKEN

Endpoints marked Auth require the token of the bot/server in the URL.

Rate limits

Public reads: 120 requests/min per IP. Posting stats: 60/min per bot. Vote checks: 120/min per bot. Exceeding a limit returns 429 with a Retry-After header.

Bots

Method	Endpoint	Description
GET	`/bots`	Search bots. Query: `search`, `tag`, `sort` (votes\|new\|trending\|popular\|total), `limit` (≤500), `offset`
GET	`/bots/:id`	Get a bot
GET	`/bots/:id/stats`	Get a bot's server & shard count
POST	`/bots/:id/stats` Auth	Body: `{"server_count": 1234, "shard_count": 2}` — `server_count` may also be an array of per-shard counts
GET	`/bots/:id/check?userId=` Auth	`{"voted": 1}` if the user voted in the last 12 hours
GET	`/bots/:id/votes` Auth	Last 1000 unique voters in the past 30 days
GET	`/weekend`	`{"is_weekend": true}` — votes count double Friday–Sunday (UTC)

Bot object

{
  "id": "123456789012345678",
  "name": "MyBot",
  "avatar": "https://cdn.discordapp.com/avatars/...",
  "shortdesc": "The best bot",
  "tags": ["moderation", "music"],
  "prefix": "!",
  "lib": "discord.js",
  "invite": "https://discord.com/oauth2/authorize?...",
  "support": "abcdef",
  "github": null,
  "website": null,
  "owners": ["987654321098765432"],
  "certifiedBot": false,
  "vanity": "mybot",
  "server_count": 1234,
  "shard_count": 2,
  "monthlyPoints": 420,
  "points": 9001,
  "date": "2026-01-01T00:00:00+00:00",
  "url": "https://rankcore.org/bot/mybot"
}

Servers

Method	Endpoint	Description
GET	`/servers/:id`	Get a server (member counts refresh from its invite)
GET	`/servers/:id/check?userId=` Auth	Has the user voted recently
GET	`/servers/:id/votes` Auth	Recent voters

Users

Method	Endpoint	Description
GET	`/users/:id`	Public profile of a user who has logged in to RankCore

Vote webhooks

Set a webhook URL and secret on your bot's Webhooks & API page. On every vote we send:

POST https://your-server.example/votes
Authorization: <your webhook secret>
Content-Type: application/json

{
  "bot": "123456789012345678",   // "guild" for servers
  "user": "987654321098765432",
  "type": "upvote",               // "test" for test webhooks
  "isWeekend": false,
  "query": ""                     // ?ref= value from the vote link
}

Respond with any 2xx status. Failed deliveries are retried up to 5 times with exponential backoff (1, 4, 16, 64 minutes). Always verify the Authorization header.

Widgets

Embed live SVG widgets in your README or website:

Widget	URL
Bot card	`https://rankcore.org/api/widget/:id.svg`
Server card	`https://rankcore.org/api/widget/servers/:id.svg`
Votes badge	`https://rankcore.org/api/widget/upvotes/:id.svg`
Servers badge	`https://rankcore.org/api/widget/servers/:id.svg` (bots: use `/widget/status/:id.svg` for status)

[![MyBot](https://rankcore.org/api/widget/123456789012345678.svg)](https://rankcore.org/bot/123456789012345678)

Examples

discord.js

// Post server count every 30 minutes
setInterval(async () => {
  await fetch(`https://rankcore.org/api/bots/${client.user.id}/stats`, {
    method: 'POST',
    headers: { Authorization: process.env.RANKCORE_TOKEN, 'Content-Type': 'application/json' },
    body: JSON.stringify({ server_count: client.guilds.cache.size, shard_count: client.shard?.count ?? 1 }),
  });
}, 30 * 60 * 1000);

// Receive votes (express)
app.post('/votes', express.json(), (req, res) => {
  if (req.headers.authorization !== process.env.RANKCORE_WEBHOOK_SECRET) return res.sendStatus(401);
  console.log(`User ${req.body.user} voted!`);
  res.sendStatus(200);
});

discord.py

import aiohttp
from discord.ext import tasks

@tasks.loop(minutes=30)
async def post_stats():
    async with aiohttp.ClientSession() as s:
        await s.post(f"https://rankcore.org/api/bots/{bot.user.id}/stats",
                     headers={"Authorization": RANKCORE_TOKEN},
                     json={"server_count": len(bot.guilds)})