Skip to main content
Use this guide when your bot needs Rankly data on demand.

​
When to use the API

  • Show server or bot stats in a command
  • Check whether a user can vote again
  • Render review summaries in your own dashboard
  • Cache Rankly data in a backend job
If you need Rankly to push updates to you, use the webhook guides instead.
1

Keep the API key server-side

Store the key in an environment variable. Do not ship it in a browser bundle or public client app.
2

Call the smallest endpoint you need

Use /server for server stats, /bot for bot stats, /votes/:userId for cooldown checks, and /reviews for review summaries.
3

Handle failures cleanly

Treat 401, 400, and 429 as normal outcomes and show a useful message instead of crashing the command.
4

Cache anything that is safe to cache

Rankings and review summaries do not usually need to be fetched for every message.

​
Example: fetch server stats

const baseUrl = 'https://api.rankly.live/api/v1';

async function getServerStats() {
  const response = await fetch(`${baseUrl}/server`, {
    headers: {
      'X-API-Key': process.env.RANKLY_API_KEY,
    },
  });

  const payload = await response.json();
  if (!payload.success) {
    throw new Error(payload.error);
  }

  return payload.data;
}

​
Example: check vote eligibility

const baseUrl = 'https://api.rankly.live/api/v1';
const userId = interaction.user.id;

const response = await fetch(`${baseUrl}/votes/${userId}`, {
  headers: {
    'X-API-Key': process.env.RANKLY_API_KEY,
  },
});

const payload = await response.json();

if (!payload.success) {
  throw new Error(payload.error);
}

if (payload.data.canVote) {
  // Show the vote button or reward hint.
}

​
Good integration habits

  • Never trust the client with your API key.
  • Use the public API for live reads, not for write operations.
  • Keep your command output short and readable.
  • Cache responses that users ask for repeatedly.
  • Add a small error message when the API key is invalid or the cooldown has not expired.

Public API Reference

Endpoint details, auth rules, and response examples.

Bot Vote Webhooks

Receive push updates when a vote is processed.