Loading...
Loading...
Everything you need to know about using TopBotList — from API integration to Discord verification and support.
Go to your Dashboard, find your bot, and generate an API token. Keep this token secret!
Include your token in the Authorization header:
Authorization: Bearer YOUR_API_TOKEN
https://topbotlist.net/api
/api/bots/{botId}/statsPost your bot's server count and other statistics.
{
"server_count": 1000, // Required: Total servers
"user_count": 50000, // Optional: Total users
"voice_connections": 25, // Optional: Active voice connections
"shard_count": 2, // Optional: Number of shards
"shards": [500, 500] // Optional: Per-shard server counts
}await fetch('https://topbotlist.net/api/bots/YOUR_BOT_ID/stats', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
server_count: client.guilds.cache.size
})
});/api/bots/{botId}/votes/{userId}Check if a user has voted for your bot in the current voting window (12 hours).
{
"voted": true,
"votedAt": "2024-01-15T12:00:00.000Z",
"expiresAt": "2024-01-16T00:00:00.000Z"
}const res = await fetch(
'https://topbotlist.net/api/bots/YOUR_BOT_ID/votes/USER_DISCORD_ID',
{ headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' } }
);
const { voted } = await res.json();
if (voted) {
// Give user vote rewards
}Configure a webhook to receive real-time notifications when users vote for your bot. Set this up in your Dashboard.
{
"bot": "YOUR_BOT_ID",
"user": "VOTER_DISCORD_ID",
"type": "vote",
"isWeekend": false,
"query": "?ref=something" // Optional query string from vote page
}Your webhook secret is sent in the Authorization header. Verify this matches your configured secret to ensure the request is from TopBotList.
/api/bots/{botId}/commandsUpload your bot's slash commands to display on your listing page.
Send an array of Discord application command objects:
[
{
"name": "help",
"description": "Get help with the bot",
"type": 1
},
{
"name": "ping",
"description": "Check bot latency",
"type": 1
}
]Embed widgets on your website or README to show your bot's stats.
<img src="https://topbotlist.net/api/bots/YOUR_BOT_ID/widget?type=servers" alt="Server Count" /> <img src="https://topbotlist.net/api/bots/YOUR_BOT_ID/widget?type=votes" alt="Vote Count" />
Options: type=servers|votes|status, style=flat|flat-square|plastic
<img src="https://topbotlist.net/api/bots/YOUR_BOT_ID/widget/large" alt="Bot Widget" />
/api/bots/{botId}Get public information about a bot. No authentication required.
{
"botId": "123456789",
"name": "My Bot",
"shortDesc": "A cool Discord bot",
"tags": ["Moderation", "Utility"],
"serverCount": 1000,
"voteCount": 500,
"inviteUrl": "https://discord.com/...",
"supportServerUrl": "https://discord.gg/...",
"websiteUrl": "https://mybot.com"
}API requests are rate limited to prevent abuse. Current limits:
Add a TopBotList badge to your bot's website, GitHub README, or documentation to show off your listing status.
/api/bots/{botId}/badgeReturns an SVG badge showing your bot's TopBotList status.
Use BotBlock to post stats to multiple bot lists including TopBotList with a single request.
See the BotBlock helper in your Dashboard for setup instructions.
To help prevent abuse and ensure a quality community, some features require you to join our Discord server and verify your account.
Need help? Our ticket system lets you submit support requests directly through the website. Tickets are synced with our Discord server for faster response times.
All tickets are also posted to a private forum channel in our Discord server. Staff can respond from either the website or Discord, and you'll receive updates in both places.
If you have questions or run into issues, submit a support ticket or join our Discord server for real-time help.