API Reference
Integrate Rank.top features into your applications with our comprehensive REST API. Manage bot listings, track analytics, handle votes, and build powerful Discord integrations.
Try Our Interactive API Explorer
Test endpoints directly from your browser
No setup required! Test our API endpoints with real data, see live responses, and generate code examples. Perfect for exploring our API before integration.
Getting Started
Base URL
All API requests should be made to this base URL. HTTPS is required for all requests.
Quick Example
https://rank.top/api/bots/123456789/details
Most endpoints require authentication. Get your API key from your dashboard.
Authentication
API Key Authentication
Most endpoints require an API key in the Authorization header
Webhook Authentication
Webhooks use a custom authorization token for security
Public Endpoints
Some read-only endpoints are publicly accessible
Getting Your API Key
You can generate and manage your API keys from your dashboard. Keep your API keys secure and never share them publicly.
API Endpoints
Bots
Manage Discord bot listings, stats, and configurations
/bots/{id}/detailsRetrieve detailed information about a specific Discord bot./bots/{id}/statsGet current statistics and analytics for a bot./bots/{id}/postUpdate your bot's server count, user count, and other statistics./bots/searchSearch for Discord bots with advanced filtering and sorting options.Servers
Manage Discord server listings and community features
/servers/{id}/detailsRetrieve detailed information about a Discord server./servers/searchSearch for Discord servers with advanced filtering and sorting options.Users
User profiles, authentication, and account management
/users/{id}/getRetrieve public profile information for a user.Analytics
Vote tracking, page views, and performance metrics
Campaigns
Advertising campaigns and promotions
Utility
Image processing, backgrounds, and miscellaneous features
Response Examples
Bot Details Response
{
"id": "123456789012345678",
"name": "Example Bot",
"avatar": "https://cdn.discordapp.com/avatars/...",
"short_desc": "A powerful Discord bot for your server",
"long_desc": "Detailed description with markdown support...",
"invite": "https://discord.com/oauth2/authorize?...",
"categories": [1, 5, 8],
"prefix": ["!", "?"],
"verified": true,
"nsfw": false,
"server_count": 1500,
"user_count": 45000,
"votes": 2840,
"votestotal": 15632,
"owner": "987654321098765432",
"support_server": "https://discord.gg/example"
}Stats Update Response
{
"server_count": 1500,
"user_count": 45000,
"ping": 45,
"memory": 256,
"commands": [
{
"id": "1234567890",
"name": "help",
"description": "Show help information",
"options": []
}
],
"last_update": "2024-01-15T10:30:00Z"
}Error Response
{
"error": "Bot not found",
"code": "BOT_NOT_FOUND",
"status": 404
}Common HTTP Status Codes
Rate Limits
Our API implements rate limiting to ensure fair usage and maintain service quality. Rate limits are applied per API key and reset every minute.
Most GET and POST operations
Search bots, servers, and users
Bot statistics posting
Voting and vote history
API key generation and validation
Public data without auth
Rate Limit Headers
All responses include rate limit headers: X-RateLimit-Limit,X-RateLimit-Remaining, andX-RateLimit-Reset.
Error Handling
All errors follow a consistent format with descriptive messages and appropriate HTTP status codes.
Error Response Format
{
"error": "Error description",
"code": "ERROR_CODE",
"status": 400,
"details": {
"field": "Additional context"
}
}Common Error Codes
SDKs & Libraries
JavaScript/Node.js
Coming Soon
Official JavaScript SDK for easy integration with Node.js applications and Discord bots.
Python
Coming Soon
Python wrapper for discord.py and other Python Discord libraries.
C# / .NET
Coming Soon
.NET library for Discord.Net and DSharpPlus applications.
Support & Community
Need Help?
Our developer community and support team are here to help you integrate with Rank.top.