Rankly Documentation - Grow Your Discord Server

Learn how to integrate the Rankly Public API into your Discord bot to access server data, verify votes, and display reviews.

Quick Start

Get up and running with the Rankly API in minutes.

1. Get Your API Key

Go to Rankly Dashboard
Select your server
Navigate to Edit Server → Advanced Setup
Copy your API Key (starts with rk_live_)

2. Make Your First Request

curl -X GET "https://api.rankly.live/api/v1/server" \
  -H "X-API-Key: rk_live_..." \
  -H "Content-Type: application/json"

3. Handle the Response

{
  "success": true,
  "data": {
    "id": "123456789012345678",
    "name": "My Awesome Server",
    "memberCount": 5000
  }
}

Common Use Cases

Display Server Stats in Bot Commands

Discord.py
Discord.js

import discord
import aiohttp
from discord.ext import commands

class RanklyBot(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
        self.api_key = "rk_live_..."
        self.base_url = "https://api.rankly.live/api/v1"
    
    @commands.command(name="stats")
    async def server_stats(self, ctx):
        """Display server stats from Rankly"""
        async with aiohttp.ClientSession() as session:
            headers = {"X-API-Key": self.api_key}
            async with session.get(
                f"{self.base_url}/server",
                headers=headers
            ) as resp:
                data = await resp.json()
                
                if data["success"]:
                    server = data["data"]
                    embed = discord.Embed(
                        title=f"📊 {server['name']} Stats",
                        color=discord.Color.green()
                    )
                    embed.add_field(
                        name="Members",
                        value=f"{server['memberCount']:,}",
                        inline=True
                    )
                    await ctx.send(embed=embed)

const { SlashCommandBuilder } = require('discord.js');
const axios = require('axios');

module.exports = {
  data: new SlashCommandBuilder()
    .setName('stats')
    .setDescription('Display server stats from Rankly'),
  
  async execute(interaction) {
    try {
      const response = await axios.get(
        'https://api.rankly.live/api/v1/server',
        { headers: { 'X-API-Key': process.env.RANKLY_API_KEY } }
      );

      if (response.data.success) {
        const server = response.data.data;
        const embed = {
          title: `📊 ${server.name} Stats`,
          color: 0x16A34A,
          fields: [
            {
              name: 'Members',
              value: `${server.memberCount.toLocaleString()}`,
              inline: true
            }
          ]
        };
        await interaction.reply({ embeds: [embed] });
      }
    } catch (error) {
      console.error('API Error:', error);
      await interaction.reply('Failed to fetch stats.');
    }
  }
};

Check if User Can Vote

Discord.py
Discord.js

@commands.command(name="canvote")
async def check_vote_status(self, ctx):
    """Check if user can vote for the server"""
    async with aiohttp.ClientSession() as session:
        headers = {"X-API-Key": self.api_key}
        user_id = ctx.author.id
        async with session.get(
            f"{self.base_url}/votes/{user_id}",
            headers=headers
        ) as resp:
            data = await resp.json()
            
            vote_data = data["data"]
            if vote_data["canVote"]:
                await ctx.send(
                    f"✅ {ctx.author.mention}, you can vote for the server!"
                )
            else:
                # Show time until next vote
                seconds = vote_data["secondsUntilVote"]
                hours = seconds // 3600
                await ctx.send(
                    f"⏳ {ctx.author.mention}, you can vote again in {hours} hours"
                )

module.exports = {
  data: new SlashCommandBuilder()
    .setName('canvote')
    .setDescription('Check if you can vote for the server'),
  
  async execute(interaction) {
    try {
      const response = await axios.get(
        `https://api.rankly.live/api/v1/votes/${interaction.user.id}`,
        { headers: { 'X-API-Key': process.env.RANKLY_API_KEY } }
      );

      const voteData = response.data.data;
      if (voteData.canVote) {
        await interaction.reply({
          content: `✅ You can vote for the server!`,
          ephemeral: true
        });
      } else {
        const hours = Math.ceil(voteData.secondsUntilVote / 3600);
        await interaction.reply({
          content: `⏳ You can vote again in ${hours} hours`,
          ephemeral: true
        });
      }
    } catch (error) {
      await interaction.reply('Failed to check vote status.');
    }
  }
};

Display Latest Reviews

Discord.py
Discord.js

@commands.command(name="reviews")
async def show_reviews(self, ctx, limit: int = 5):
    """Show latest reviews from Rankly"""
    if limit > 50:
        limit = 50
    
    async with aiohttp.ClientSession() as session:
        headers = {"X-API-Key": self.api_key}
        async with session.get(
            f"{self.base_url}/reviews?limit={limit}&sort=newest",
            headers=headers
        ) as resp:
            data = await resp.json()
            
            if data["success"] and data["data"]:
                embed = discord.Embed(
                    title="⭐ Latest Reviews",
                    color=discord.Color.gold()
                )
                for review in data["data"][:5]:
                    embed.add_field(
                        name=f"{review['username']} - {review['rating']}⭐",
                        value=review['comment'][:256],
                        inline=False
                    )
                await ctx.send(embed=embed)

module.exports = {
  data: new SlashCommandBuilder()
    .setName('reviews')
    .setDescription('Show latest reviews')
    .addIntegerOption(option =>
      option
        .setName('limit')
        .setDescription('Number of reviews (max 50)')
        .setRequired(false)
    ),
  
  async execute(interaction) {
    const limit = interaction.options.getInteger('limit') || 5;
    
    try {
      const response = await axios.get(
        `https://api.rankly.live/api/v1/reviews?limit=${limit}`,
        { headers: { 'X-API-Key': process.env.RANKLY_API_KEY } }
      );

      if (response.data.success && response.data.data.length > 0) {
        const embed = {
          title: '⭐ Latest Reviews',
          color: 0xFFA500,
          fields: response.data.data.slice(0, 5).map(review => ({
            name: `${review.username} - ${review.rating}⭐`,
            value: review.comment.substring(0, 256),
            inline: false
          }))
        };
        await interaction.reply({ embeds: [embed] });
      }
    } catch (error) {
      await interaction.reply('Failed to fetch reviews.');
    }
  }
};

Advanced Integration

Cache API Responses

To avoid hitting rate limits and improve performance, cache responses:

const axios = require('axios');
const NodeCache = require('node-cache');

const cache = new NodeCache({ stdTTL: 300 }); // 5 minute cache

async function getServerDetails() {
  const cacheKey = 'rankly_server_details';
  
  // Check cache first
  let cached = cache.get(cacheKey);
  if (cached) return cached;
  
  // Fetch from API
  const response = await axios.get(
    'https://api.rankly.live/api/v1/server',
    { headers: { 'X-API-Key': process.env.RANKLY_API_KEY } }
  );
  
  // Store in cache
  cache.set(cacheKey, response.data);
  return response.data;
}

Error Handling with Retry Logic

async function fetchWithRetry(url, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await axios.get(url, {
        headers: { 'X-API-Key': process.env.RANKLY_API_KEY }
      });
      return response.data;
    } catch (error) {
      if (error.response?.status === 429) {
        // Rate limited - wait and retry
        const delay = Math.pow(2, i) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
}

Troubleshooting

401 Unauthorized

Verify your API Key is correct
Ensure the key is passed in the X-API-Key header
Check that the key hasn’t expired
Regenerate the key in your dashboard if needed

429 Too Many Requests

You’ve exceeded 120 requests per minute
Implement caching to reduce API calls
Add delay between requests
Use exponential backoff for retries

404 Not Found

Verify the API endpoint is correct
Check that your server exists on Rankly
Ensure you’re using the correct base URL

Next Steps

API Reference

Full API documentation with all endpoints

Vote Webhooks

Receive real-time vote notifications

Premium Webhooks

Handle premium purchases in real-time

API Integration

Webhooks

Bot API Integration

Quick Start

1. Get Your API Key

2. Make Your First Request

3. Handle the Response

Common Use Cases

Display Server Stats in Bot Commands

Check if User Can Vote

Display Latest Reviews

Advanced Integration

Cache API Responses

Error Handling with Retry Logic

Troubleshooting

Next Steps

API Reference

Vote Webhooks

Premium Webhooks

API Integration

Webhooks

​Quick Start

​1. Get Your API Key

​2. Make Your First Request

​3. Handle the Response

​Common Use Cases

​Display Server Stats in Bot Commands

​Check if User Can Vote

​Display Latest Reviews

​Advanced Integration

​Cache API Responses

​Error Handling with Retry Logic

​Troubleshooting

​Next Steps

API Reference

Vote Webhooks

Premium Webhooks

Quick Start

1. Get Your API Key

2. Make Your First Request

3. Handle the Response

Common Use Cases

Display Server Stats in Bot Commands

Check if User Can Vote

Display Latest Reviews

Advanced Integration

Cache API Responses

Error Handling with Retry Logic

Troubleshooting

Next Steps