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
Get your API key
Dashboard → your server → Game integration → Generate API key.
- 2
Send heartbeats
Optional: POST your player count every 1–15 minutes to show as Online.
- 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.
{
"apiKey": "YOUR_API_KEY",
"players": 127
}{
"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 links
Send players to your vote page. Adding ?u= fills in their in-game name automatically, so the vote is credited to the right account.
https://www.getranqed.com/vote/YOUR-SERVER-SLUG?u=PlayerNameYour slug and full link are shown on your server's page in the dashboard. Each player can vote once every 12 hours per server.
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.
GET https://yourserver.com/vote/callback?username=Zezima&usr=Zezima&server=your-server&votes=125×tamp=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 ofusername:timestampusing 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 ascallback:https://www.getranqed.com/vote/your-server?u={username}&callback={incentive}. RanQed sends it back to your callback URL aspostback,callbackandincentive(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.
{
"apiKey": "YOUR_API_KEY",
"username": "PlayerName"
}{
"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.
{
"apiKey": "YOUR_API_KEY",
"username": "PlayerName"
}{
"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.
// 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
| Status | Meaning |
|---|---|
| 200 | Success. Check the JSON fields (e.g. claimed: false means no vote to claim). |
| 400 | Bad request: missing fields, invalid JSON, an invalid player count, or a username over 20 characters. |
| 401 | Invalid API key. Regenerate it from your dashboard if it was lost. |
| 500 | Something went wrong on our side. Retry with a short delay. |
Every error response includes a human-readable message.