Developers

Vote API

Automatically reward players who vote for your server: your plugin checks the vote on Rank-Serv and marks it as claimed.

Getting started

It works in three steps:

Get your server's vote token from your owner area.
The player votes on Rank-Serv with their in-game name.
When they type a command in game (for example /vote), your plugin calls /claim and gives the reward if the response is CLAIMED.

Authentication

Every request must include your server token in the following HTTP header. Plugins that can't send headers may use the ?token= parameter instead.

X-Server-Token: VOTRE_TOKEN

You can find the token on your server's edit page, from My servers.

Keep this token secret: it lets anyone claim your server's votes. If it leaks, regenerate it from the edit page. The old token stops working immediately.

Check a vote

GEThttps://api.rank-serv.com/v1/votes/check

Tells whether the player voted in the last 2 hours and whether the reward was already claimed. This call changes nothing.

Parameter	Required	Description
token	Yes	Server token, in the X-Server-Token header or as ?token= parameter.
username	One of	Name entered by the player when voting (case-insensitive).
ip	One of	Player's IP address at vote time. Don't send username and ip together.

curl -H "X-Server-Token: VOTRE_TOKEN" \
  "https://api.rank-serv.com/v1/votes/check?username=Steve"

{
  "status": "CLAIMABLE",
  "voted_at": "2026-11-05T14:02:11",
  "next_vote_in": 4320
}

Claim a vote

POSThttps://api.rank-serv.com/v1/votes/claim

Marks the player's latest vote as claimed. A vote can only be claimed once, even if two requests arrive at the same time: only give the reward when the status is CLAIMED.

Parameters are the same as for /check.

curl -X POST -H "X-Server-Token: VOTRE_TOKEN" \
  "https://api.rank-serv.com/v1/votes/claim?username=Steve"

{
  "status": "CLAIMED",
  "voted_at": "2026-11-05T14:02:11",
  "next_vote_in": 4318
}

Responses

Both endpoints always return HTTP 200 with this JSON format, whether the vote exists or not.

Fields

status: Result of the request (see below).
voted_at: Date and time of the vote, or null if no vote was found.
next_vote_in: Seconds until the player can vote again, or null.

Status values

NOT_FOUND: No vote from this player in the last 2 hours.
CLAIMABLE: /check only: the player voted and the reward hasn't been claimed yet.
CLAIMED: /claim only: the vote was just claimed, give the reward.
ALREADY_CLAIMED: The vote was already claimed, don't give the reward twice.

{
  "status": "NOT_FOUND",
  "voted_at": null,
  "next_vote_in": null
}

Errors

Any HTTP code other than 200 means the request is invalid:

400: Missing parameter: send username or ip, but not both.
401: Missing token.
404: Invalid token: no server matches.

Examples

Complete examples for claiming a vote.

curl -X POST -H "X-Server-Token: VOTRE_TOKEN" \
  "https://api.rank-serv.com/v1/votes/claim?ip=203.0.113.42"

Best practices

Prefer looking up by username: the browser IP at vote time may differ from the one your game server sees (IPv6/IPv4, mobile, VPN).
Call /claim directly when the player types the command. You don't need to call /check first.
Don't poll the API for every connected player: only call it when the player asks.
Make calls asynchronously so your server never blocks.
Prefer the X-Server-Token header: a token in the URL may end up in logs.