Skip to main content
The public API is read-only and requires an API key tied to a Rankly server or bot.

​
Base URL

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

​
Authentication

Send your API key in the X-API-Key header. 
curl https://api.rankly.live/api/v1/server \
  -H "X-API-Key: rk_live_your_key_here"
You can also provide the key as ?key=..., but the header is the preferred form.

​
Response shape

Most endpoints return a standard envelope: 
{
  "success": true,
  "data": {},
  "meta": {}
}
Errors return: 
{
  "success": false,
  "error": "Message here"
}

​
Endpoints at a glance

MethodPathUse it forWorks for
GET/serverFetch the authenticated server profile and stats.Servers only
GET/botFetch the authenticated bot profile and stats.Bots only
GET/votes/:userIdCheck vote cooldown and eligibility for a specific user.Servers or bots
GET/reviewsRead the authenticated server reviews.Servers only

​
GET /server

Returns the server metadata for the API key owner.

​
Example response

{
  "success": true,
  "data": {
    "id": "123456789012345678",
    "name": "Rankly Community",
    "description": "A friendly Discord community.",
    "votes": 124,
    "monthlyVotes": 37,
    "tags": ["discord", "community"],
    "category": "Community",
    "ownerDiscordId": "234567890123456789",
    "features": [],
    "emojis": [],
    "channelCount": 12,
    "roleCount": 18,
    "rules": [],
    "url": "https://rankly.live/server/123456789012345678",
    "stats": {
      "members": 842,
      "online": 114
    }
  }
}

​
GET /bot

Returns the bot metadata for the API key owner.

​
Example response

{
  "success": true,
  "data": {
    "id": "987654321098765432",
    "name": "Rankly Bot",
    "description": "Bot utilities and rewards.",
    "votes": 52,
    "tags": [],
    "url": "https://rankly.live/bot/987654321098765432",
    "stats": {
      "servers": 0,
      "shards": 0
    }
  }
}

​
GET /votes/:userId

Checks whether a user can vote again right now.

​
Path parameters

ParameterTypeDescription
userIdstringDiscord user ID to check. Must be numeric.

​
Example response

{
  "success": true,
  "data": {
    "canVote": false,
      "nextVoteDate": "2026-01-02T00:00:00.000Z",
    "lastVoteDate": "2026-01-01T12:00:00.000Z",
    "secondsUntilVote": 43200
  }
}
The cooldown window is 12 hours.

​
GET /reviews

Returns reviews for the authenticated server.

​
Query parameters

ParameterTypeDefaultDescription
limitnumber10Maximum reviews to return. The hard cap is 50.
sortstringnewestUse newest, highest, or lowest.

​
Example response

{
  "success": true,
  "data": [
    {
      "username": "Skyline",
      "rating": 5,
      "comment": "Very active and welcoming.",
      "createdAt": "2026-01-01T12:00:00.000Z"
    }
  ],
  "meta": {
    "total": 14,
    "shown": 1
  }
}

​
Example client code

const response = await fetch('https://api.rankly.live/api/v1/server', {
  headers: {
    'X-API-Key': process.env.RANKLY_API_KEY,
  },
});

const payload = await response.json();

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

console.log(payload.data.name);

​
Error handling

  • 401 means the key is missing or invalid.
  • 400 means the endpoint does not match the key type or the parameter is invalid.
  • 429 means the request limit was exceeded.
  • 500 means the backend hit an unexpected error.

​
Best practices

  • Keep the API key on your server.
  • Cache responses that do not need to change every second.
  • Use /votes/:userId only when you need the live cooldown state.
  • Prefer the public API reference over reverse-engineering dashboard calls.