REST API v1

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.

7 endpointsRESTJSON24/7On the routes:Use the API

Try our interactive API explorer

You can test our API endpoints directly from your browser and get real-time data!

Launch explorer View docs

Getting started#

Base URL

https://rank.top/api

All API requests should be made to this base URL. HTTPS is required for all requests.

Quick example

curl -H "Authorization: Bearer YOUR_API_KEY" \
  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

Authorization: Bearer your_api_key_here

Webhook authentication

Webhooks use a custom authorization token for security

Authorization: your_webhook_token

Public endpoints

Some read-only endpoints are publicly accessible

No authentication required

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#

Each endpoint opens in the explorer, where you can send a real request.

Bots

Manage Discord bot listings, stats, and configurations

Try bots endpoints in the explorer4 endpoints available

Servers

Manage Discord server listings and community features

Try servers endpoints in the explorer2 endpoints available

Users

User profiles, authentication, and account management

GET/users/{id}/getRetrieve public profile information for a user.

Try users endpoints in the explorer1 endpoint available

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

200 OKRequest successful

400 Bad RequestInvalid request data

401 UnauthorizedInvalid or missing API key

404 Not FoundResource not found

429 Too Many RequestsRate limit exceeded

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.

General endpointsMost GET and POST operations60/min

Search operationsSearch bots, servers, and users30/min

Stats updatesBot statistics posting12/hour

Vote operationsVoting and vote history10/min

AuthenticationAPI key generation and validation5/min

Public endpointsPublic data without auth120/min

Rate limit headers

All responses include rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, and X-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

INVALID_API_KEY: The provided API key is invalid or expired
BOT_NOT_FOUND: The specified bot ID does not exist
RATE_LIMIT_EXCEEDED: Too many requests, please slow down
VALIDATION_ERROR: Request data failed validation

SDKs and 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.

More resources

Getting started guideRead the guide

Bot integration guideComing soon

API status pageCheck status