Developers

Integration docs

Connect your RSPS to Ranqed for live player counts and automatic in-game vote rewards. Three simple JSON endpoints, no SDK needed.

Quick start

  1. 1

    Get your API key

    Dashboard → your server → Game integration → Generate API key.

  2. 2

    Send heartbeats

    Optional: POST your player count every 1–15 minutes to show as Online.

  3. 3

    Reward voters

    Share your vote link, then claim votes in-game to give rewards.

All requests are POST with a Content-Type: application/json body. Keep your API key on your server only; never put it in a client or website.

Server heartbeat

Optional. Send this every 1–15 minutes, whatever suits you. A server shows as Online for 35 minutes after its last heartbeat. Servers that never link show no status at all (never "Offline"), and owners can hide their player count in Manage server. Rankings are always based on verified votes, not player counts.

POSThttps://www.getranqed.com/api/servers/status
Request
{
  "apiKey": "YOUR_API_KEY",
  "players": 127
}
Response
{
  "success": true,
  "message": "Server status updated.",
  "server": "Your Server",
  "players": 127,
  "lastHeartbeat": "2026-10-02T12:00:00.000Z"
}

players must be a whole number between 0 and 100,000.

Vote callback

Already reward voters through your website, like with other toplists? Paste your callback URL in Dashboard → Manage server → Vote rewards. Every time someone votes, RanQed sends a GET request to it straight away, and your website gives the reward.

Example request
GET https://yourserver.com/vote/callback?username=Zezima&usr=Zezima&server=your-server&votes=125&timestamp=1767225600&secret=rqcb_…&signature=…
  • username / usr: the in-game name the player entered.
  • server: your RanQed server slug. votes: your new total.
  • secret: your callback secret from the dashboard. Check it so nobody else can trigger rewards.
  • signature (optional extra check): HMAC-SHA256 hex of username:timestamp using your secret.
  • Need a different format? Use placeholders in your URL: {username}, {server}, {secret}, {timestamp}, e.g. https://yoursite.com/vote.php?name={username}&key={secret}.
  • Using vote tokens (like {incentive} on other toplists)? Add it to your RanQed vote link as callback: https://www.getranqed.com/vote/your-server?u={username}&callback={incentive}. RanQed sends it back to your callback URL as postback, callback and incentive (or wherever you put {incentive} in your callback URL).
  • Answer with status 200. The vote is then marked claimed, so it can't be rewarded again through the claim API. Use Send test vote in the dashboard to check your setup (it sends the username RanQedTest).

Check pending votes

Check whether a player has votes waiting to be rewarded, e.g. on login.

POSThttps://www.getranqed.com/api/votes/pending
Request
{
  "apiKey": "YOUR_API_KEY",
  "username": "PlayerName"
}
Response
{
  "success": true,
  "server": "Your Server",
  "username": "PlayerName",
  "hasVote": true,
  "pendingVotes": 1
}

Claim a vote reward

Marks the player's oldest unclaimed vote as claimed. Only give the reward when claimed is true; each vote can be claimed once.

POSThttps://www.getranqed.com/api/votes/claim
Request
{
  "apiKey": "YOUR_API_KEY",
  "username": "PlayerName"
}
Response
{
  "success": true,
  "claimed": true,
  "message": "Vote claimed successfully.",
  "server": "Your Server",
  "username": "PlayerName",
  "voteId": 123,
  "votedAt": "2026-10-02T11:58:00.000Z",
  "claimedAt": "2026-10-02T12:00:00.000Z"
}

Java example

A typical RSPS setup. post() is your HTTP helper (e.g. using HttpURLConnection or OkHttp). Run network calls off the game thread.

Java (RSPS)
// 1) Every 1-15 minutes: report your player count
post("https://www.getranqed.com/api/servers/status",
     "{\"apiKey\":\"" + API_KEY + "\",\"players\":" + World.getPlayers().size() + "}");

// 2) When a player types ::claimvote (or logs in)
String body = "{\"apiKey\":\"" + API_KEY + "\",\"username\":\"" + player.getUsername() + "\"}";
JSONObject result = post("https://www.getranqed.com/api/votes/claim", body);

if (result.getBoolean("claimed")) {
    player.getInventory().add(VOTE_REWARD);
    player.sendMessage("Thanks for voting! Your reward has been added.");
} else {
    player.sendMessage("No unclaimed vote found. Vote at https://www.getranqed.com/vote");
}

Errors & limits

StatusMeaning
200Success. Check the JSON fields (e.g. claimed: false means no vote to claim).
400Bad request: missing fields, invalid JSON, an invalid player count, or a username over 20 characters.
401Invalid API key. Regenerate it from your dashboard if it was lost.
500Something went wrong on our side. Retry with a short delay.

Every error response includes a human-readable message.