Rankly Documentation - Grow Your Discord Server

Everything you need to integrate Rankly into your bot or application in one place.

Choose Your Integration Path

I'm a Bot Developer

Want to integrate Rankly features into your Discord bot?Start with: Bot API IntegrationLearn how to:

Display server stats in commands
Check if users can vote
Show latest reviews

I Own a Server

Want to receive real-time vote notifications?Start with: Server WebhooksLearn how to:

Configure webhook endpoints
Process vote events
Build reward systems

I Need the API Reference

Looking for complete API documentation?Start with: API ReferenceLearn about:

All available endpoints
Authentication methods
Response formats

I Handle Premium Features

Need to process premium purchases?Start with: Premium WebhooksLearn how to:

Receive purchase events
Activate user/server premium
Handle subscriptions

Quick Comparisons

API vs Webhooks

Feature	API	Webhooks
Direction	Pull (you request)	Push (we notify)
Latency	Higher (polling needed)	Lower (instant)
Rate Limited	Yes (120/min)	No
Best For	Occasional queries	Real-time reactions
Setup	Just get API key	Need public endpoint

Use API when: You need data on-demand (commands, dashboards) Use Webhooks when: You need to react immediately to events

Bot API Integration vs Vote Webhooks

Scenario	Use Bot API Integration	Use Vote Webhooks
Display vote count in command	✅ `/stats`	❌
Auto-reward votes in bot	❌	✅
Check if user can vote	✅	❌
Track vote trends	Both	Webhooks better
Show latest reviews	✅	❌
Instant vote processing	❌	✅

5-Minute Setup Guides

For Bot Developers: Display Server Stats

Get API Key

Visit Rankly Dashboard → Edit Server → Advanced Setup → Copy API Key

Install Dependencies

Node.js
Python

npm install axios

pip install requests

Create Command Handler

Discord.js
Discord.py

const axios = require('axios');

module.exports = {
  data: new SlashCommandBuilder()
    .setName('stats')
    .setDescription('Show 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) {
      await interaction.reply('Failed to fetch stats.');
    }
  }
};

import discord
import aiohttp
from discord.ext import commands

class Stats(commands.Cog):
  def __init__(self, bot):
    self.bot = bot
    self.api_key = "rk_live_..."
    
  @commands.command(name="stats")
  async def server_stats(self, ctx):
    async with aiohttp.ClientSession() as session:
      headers = {"X-API-Key": self.api_key}
      async with session.get(
        "https://api.rankly.live/api/v1/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)

Test It

Run /stats in your Discord server and watch it work!

For Server Owners: Set Up Vote Webhooks

Prepare Your Endpoint

You’ll need a publicly accessible HTTPS endpoint. Here’s a minimal example:

const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhook/votes', (req, res) => {
  console.log('Vote received:', req.body);
  res.status(200).json({ received: true });
});

app.listen(3000, () => console.log('Server running'));

Deploy Endpoint

Deploy to a service like:

Heroku
Railway
Render
Your own VPS

Make sure it’s accessible at a public HTTPS URL

Configure Webhook

Go to Rankly Dashboard
Click your server
Find “Vote Webhooks” section
Paste your endpoint URL
Click “Test Webhook”

Implement Reward Logic

Add code to process votes and grant rewards:

async function processVote(userId, serverId) {
  // Record in database
  await db.votes.insert({ userId, serverId, date: new Date() });
  
  // Grant reward
  await grantCurrency(userId, 100);
  
  console.log(`Rewarded ${userId} for voting!`);
}

Common Scenarios

”I want to show vote rewards eligibility”

Solution

Use the API to check vote status:

// Check if user can vote
const response = await axios.get(
  `https://api.rankly.live/api/v1/votes/${userId}`,
  { headers: { 'X-API-Key': process.env.RANKLY_API_KEY } }
);

if (response.data.data.canVote) {
  // Show "Vote now!" button
} else {
  const hours = Math.ceil(
    response.data.data.secondsUntilVote / 3600
  );
  // Show "Vote again in X hours"
}

“I want to auto-reward votes”

Solution

Use webhooks to receive instant notifications:

app.post('/webhook/votes', async (req, res) => {
  const { userId, creditsAwarded } = req.body;
  
  // Immediately grant reward
  if (!creditsAwarded) {
    // User might have ad blocker, but reward anyway
    await grantReward(userId, 100);
  } else {
    await grantReward(userId, 100);
  }
  
  res.status(200).json({ received: true });
});

“I need to track vote trends”

Solution

Combine API + Webhooks:With webhooks: Record all votes in real-timeWith API: Periodically fetch reviews to understand sentiment

// Record from webhook
app.post('/webhook/votes', async (req, res) => {
  await db.votes.insert(req.body);
  res.status(200).json({ received: true });
});

// Analyze trends
app.get('/trends', async (req, res) => {
  const last24h = await db.votes.countDocuments({
    timestamp: { $gte: new Date(Date.now() - 86400000) }
  });
  res.json({ votes24h: last24h });
});

Secrets & Configuration

Never hardcode API keys or webhook secrets in your source code!

Environment Variables

Create a .env file:

# API Key for accessing Rankly API
RANKLY_API_KEY=rk_live_...

# Webhook secrets for verification
RANKLY_VOTE_WEBHOOK_SECRET=secret_...
RANKLY_PREMIUM_WEBHOOK_SECRET=secret_...

# Your webhook endpoint
WEBHOOK_URL=https://your-domain.com/webhooks

Loading in Code

Node.js
Python

require('dotenv').config();

const apiKey = process.env.RANKLY_API_KEY;
const voteSecret = process.env.RANKLY_VOTE_WEBHOOK_SECRET;

import os
from dotenv import load_dotenv

load_dotenv()

api_key = os.getenv('RANKLY_API_KEY')
vote_secret = os.getenv('RANKLY_VOTE_WEBHOOK_SECRET')

Error Handling

API Errors

async function getServerDetails() {
  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) {
      console.error('API Error:', response.data.error);
      return null;
    }

    return response.data.data;
  } catch (error) {
    if (error.response?.status === 401) {
      console.error('Invalid API key');
    } else if (error.response?.status === 429) {
      console.error('Rate limited - wait before retrying');
    } else {
      console.error('Network error:', error.message);
    }
    return null;
  }
}

Webhook Signature Verification

Always verify signatures:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

app.post('/webhook/votes', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  
  if (!verifySignature(req.body, signature, process.env.RANKLY_VOTE_WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Safe to process
  res.status(200).json({ received: true });
});

Testing & Debugging

Test API Calls with cURL

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

# Check vote status
curl -X GET "https://api.rankly.live/api/v1/votes/987654321098765432" \
  -H "X-API-Key: rk_live_..."

# Get reviews
curl -X GET "https://api.rankly.live/api/v1/reviews?limit=5&sort=highest" \
  -H "X-API-Key: rk_live_..."

Test Webhooks with Webhook.site

Go to webhook.site
Copy the unique URL
Paste into Rankly dashboard
Click “Test Webhook”
See the payload appear on webhook.site

Local Testing with ngrok

# Start your local server
npm start  # or python app.py

# In another terminal, expose it
ngrok http 3000

# Use the ngrok URL in Rankly dashboard
# ngrok gives you: https://xxxx-xx-xxx-xxx-xxx.ngrok.io

Next Steps

API Reference

Full endpoint documentation

Bot Integration

Detailed bot examples

Vote Webhooks

Webhook implementation guide

Premium Webhooks

Handle premium purchases

Server Webhooks

Server-side webhook setup

Community

Get help from our community

Cheat Sheet

Authentication

Header: X-API-Key: rk_live_...
Query:  ?key=rk_live_...

Base URL

https://api.rankly.live/api/v1

Endpoints

GET /server          - Server details
GET /bot            - Bot details
GET /votes/{id}     - Check if user can vote
GET /reviews        - Get server reviews

Webhook Events

bot_vote            - User voted for bot
premium_purchase    - Premium purchase
server_vote         - Server received a vote

Rate Limits

120 requests per minute per API Key

Still have questions? Join our Discord community! 🎉

Welcome

API & Webhook Quick Start

Choose Your Integration Path

I'm a Bot Developer

I Own a Server

I Need the API Reference

I Handle Premium Features

Quick Comparisons

API vs Webhooks

Bot API Integration vs Vote Webhooks

5-Minute Setup Guides

For Bot Developers: Display Server Stats

For Server Owners: Set Up Vote Webhooks

Common Scenarios

”I want to show vote rewards eligibility”

“I want to auto-reward votes”

“I need to track vote trends”

Secrets & Configuration

Environment Variables

Loading in Code

Error Handling

API Errors

Webhook Signature Verification

Testing & Debugging

Test API Calls with cURL

Test Webhooks with Webhook.site

Local Testing with ngrok

Next Steps

API Reference

Bot Integration

Vote Webhooks

Premium Webhooks

Server Webhooks

Community

Cheat Sheet

Authentication

Base URL

Endpoints

Webhook Events

Rate Limits

Welcome

​Choose Your Integration Path

I'm a Bot Developer

I Own a Server

I Need the API Reference

I Handle Premium Features

​Quick Comparisons

​API vs Webhooks

​Bot API Integration vs Vote Webhooks

​5-Minute Setup Guides

​For Bot Developers: Display Server Stats

​For Server Owners: Set Up Vote Webhooks

​Common Scenarios

​”I want to show vote rewards eligibility”

​“I want to auto-reward votes”

​“I need to track vote trends”

​Secrets & Configuration

​Environment Variables

​Loading in Code

​Error Handling

​API Errors

​Webhook Signature Verification

​Testing & Debugging

​Test API Calls with cURL

​Test Webhooks with Webhook.site

​Local Testing with ngrok

​Next Steps

API Reference

Bot Integration

Vote Webhooks

Premium Webhooks

Server Webhooks

Community

​Cheat Sheet

​Authentication

​Base URL

​Endpoints

​Webhook Events

​Rate Limits

Choose Your Integration Path

Quick Comparisons

API vs Webhooks

Bot API Integration vs Vote Webhooks

5-Minute Setup Guides

For Bot Developers: Display Server Stats

For Server Owners: Set Up Vote Webhooks

Common Scenarios

”I want to show vote rewards eligibility”

“I want to auto-reward votes”

“I need to track vote trends”

Secrets & Configuration

Environment Variables

Loading in Code

Error Handling

API Errors

Webhook Signature Verification

Testing & Debugging

Test API Calls with cURL

Test Webhooks with Webhook.site

Local Testing with ngrok

Next Steps

Cheat Sheet

Authentication

Base URL

Endpoints

Webhook Events

Rate Limits