Rankly Docs

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

Method	Path	Use it for	Works for
GET	`/server`	Fetch the authenticated server profile and stats.	Servers only
GET	`/bot`	Fetch the authenticated bot profile and stats.	Bots only
GET	`/votes/:userId`	Check vote cooldown and eligibility for a specific user.	Servers or bots
GET	`/reviews`	Read 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

Parameter	Type	Description
`userId`	string	Discord 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

Parameter	Type	Default	Description
`limit`	number	`10`	Maximum reviews to return. The hard cap is 50.
`sort`	string	`newest`	Use `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

JavaScript
cURL

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);

curl "https://api.rankly.live/api/v1/votes/123456789012345678" \
  -H "X-API-Key: rk_live_your_key_here"

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.

API and help

Public API Reference

Base URL

Authentication

Response shape

Endpoints at a glance

`GET /server`

Example response

`GET /bot`

Example response

`GET /votes/:userId`

Path parameters

Example response

`GET /reviews`

Query parameters

Example response

Example client code

Error handling

Best practices

​Base URL

​Authentication

​Response shape

​Endpoints at a glance

​GET /server

​Example response

​GET /bot

​Example response

​GET /votes/:userId

​Path parameters

​Example response

​GET /reviews

​Query parameters

​Example response

​Example client code

​Error handling

​Best practices

Base URL

Authentication

Response shape

Endpoints at a glance

`GET /server`

Example response

`GET /bot`

Example response

`GET /votes/:userId`

Path parameters

Example response

`GET /reviews`

Query parameters

Example response

Example client code

Error handling

Best practices