API

Example request

curl "https://voxelrank.com/api/v1/server" \
  -H "X-Api-Key: demo"

Example response 200

{
  "id": 8685,
  "name": "Pear SMP",
  "slug": "pear-smp",
  "ip": "play.pearsmp.net",
  "bedrock": null,
  "apply_url": null,
  "version": "1.21.4",
  "country": "US",
  "tags": [
    "survival",
    "smp"
  ],
  "languages": [
    "en"
  ],
  "online": true,
  "players": 47,
  "max_players": 200,
  "motd": "Pear SMP · Season 3",
  "votes_month": 312,
  "votes_total": 4120,
  "tier": 0,
  "url": "https://voxelrank.com/server/8685-pear-smp",
  "vote_url": "https://voxelrank.com/vote/8685-pear-smp",
  "banner": "https://voxelrank.com/banner/pear-smp.svg",
  "rank": 12,
  "month": "2026-09"
}

Errors

• 401 Missing or wrong key. {"error":"invalid_key"}
• 429 More than 120 requests a minute. Wait retry_after seconds (also in the Retry-After header). {"error":"rate_limited","retry_after":12}

Parameters

days

integer (1–90, default 30)

How many days the daily series covers, 1 to 90. Default 30.

Example request

curl "https://voxelrank.com/api/v1/stats" \
  -H "X-Api-Key: demo"

Example response 200

{
  "month": "2026-09",
  "votes_today": 18,
  "votes_month": 312,
  "votes_total": 4120,
  "unique_voters_month": 64,
  "rank": 12,
  "daily": [
    {
      "date": "2026-09-25",
      "votes": 24
    },
    {
      "date": "2026-09-26",
      "votes": 17
    },
    {
      "date": "2026-09-27",
      "votes": 18
    }
  ]
}

Errors

• 401 Missing or wrong key. {"error":"invalid_key"}
• 429 More than 120 requests a minute. Wait retry_after seconds (also in the Retry-After header). {"error":"rate_limited","retry_after":12}

Parameters

month	string	Month, YYYY-MM (UTC). Default: this month.
limit	integer (1–100, default 10)	How many, 1 to 100. Default 10.

Example request

curl "https://voxelrank.com/api/v1/top?month=2026-09" \
  -H "X-Api-Key: demo"

Example response 200 · Most votes first; a tie goes to whoever reached it first.

[
  {
    "username": "Notch",
    "votes": 27,
    "last_vote": 1790000000
  },
  {
    "username": "Alex",
    "votes": 25,
    "last_vote": 1789996400
  }
]

Errors

• 400 month is not YYYY-MM. {"error":"bad_month"}
• 401 Missing or wrong key. {"error":"invalid_key"}
• 429 More than 120 requests a minute. Wait retry_after seconds (also in the Retry-After header). {"error":"rate_limited","retry_after":12}

For syncing votes into your own system: keep the last next_after you saw and ask for after= it next time.

Parameters

after	integer	Only votes with a larger id. Default 0 (from the start).
since	integer	Only votes cast at or after this unix time.
limit	integer (1–500, default 100)	Page size, 1 to 500. Default 100.

Example request

curl "https://voxelrank.com/api/v1/votes" \
  -H "X-Api-Key: demo"

Example response 200

{
  "votes": [
    {
      "id": 2045812,
      "username": "Notch",
      "timestamp": 1790000000,
      "claimed": true
    },
    {
      "id": 2045813,
      "username": "Alex",
      "timestamp": 1790000240,
      "claimed": false
    }
  ],
  "next_after": null
}

Errors

• 401 Missing or wrong key. {"error":"invalid_key"}
• 429 More than 120 requests a minute. Wait retry_after seconds (also in the Retry-After header). {"error":"rate_limited","retry_after":12}

The reward loop: fetch these, give the rewards, then claim the ids so they are not returned again.

Parameters

limit

integer (1–500, default 100)

1 to 500. Default 100.

Example request

curl "https://voxelrank.com/api/v1/votes/unclaimed" \
  -H "X-Api-Key: demo"

Example response 200 · Oldest first.

[
  {
    "id": 2045812,
    "username": "Notch",
    "timestamp": 1790000000
  },
  {
    "id": 2045813,
    "username": "Alex",
    "timestamp": 1790000240
  }
]

Errors

• 401 Missing or wrong key. {"error":"invalid_key"}
• 429 More than 120 requests a minute. Wait retry_after seconds (also in the Retry-After header). {"error":"rate_limited","retry_after":12}

Two ways, told apart by the body: - ids: the vote ids you got from /v1/votes/unclaimed. Answers { claimed }. - steamid or username (no ids): every unclaimed vote of that player from the last 24 hours, claimed in one step, so two calls at once cannot both get them. username only matches votes made by typing a name. Answers { steamid | username, claimed, ids, status }. Give the reward when claimed is above 0.

Request body

Example request

curl -X POST "https://voxelrank.com/api/v1/votes/claim" \
  -H "X-Api-Key: demo"

Example response 200

{
  "claimed": 2
}

Errors

• 400 steamid is not 17 digits, or username is too long. {"error":"bad_steamid"}
• 401 Missing or wrong key. {"error":"invalid_key"}
• 429 More than 120 requests a minute. Wait retry_after seconds (also in the Retry-After header). {"error":"rate_limited","retry_after":12}

Send username, or steamid for a Steam game. The answer by steamid also has status: 0 = no vote in the last 24 hours, 1 = voted and not claimed yet, 2 = voted and already claimed.

Parameters

username	string	Player name (case-insensitive).
steamid	string	A player's steamid64, 17 digits. Used instead of username when sent.

Example request

curl "https://voxelrank.com/api/v1/votes/check?username=Notch&steamid=76561197960287930" \
  -H "X-Api-Key: demo"

Example response 200

{
  "username": "Notch",
  "voted_recently": true,
  "last_vote": 1790000000,
  "total": 140,
  "month": 27
}

Errors

• 400 steamid is not 17 digits. {"error":"bad_steamid"}
• 401 Missing or wrong key. {"error":"invalid_key"}
• 429 More than 120 requests a minute. Wait retry_after seconds (also in the Retry-After header). {"error":"rate_limited","retry_after":12}

Parameters

username *	string	Player name.
limit	integer (1–200, default 100)	1 to 200. Default 100.

Example request

curl "https://voxelrank.com/api/v1/player/votes?username=Notch" \
  -H "X-Api-Key: YOUR_KEY"

Example response 200

{
  "username": "Notch",
  "cooldown_hours": 24,
  "servers": [
    {
      "id": 8685,
      "name": "Pear SMP",
      "slug": "pear-smp",
      "votes": 27,
      "last_vote": 1790000000,
      "cooldown_left": 3600,
      "cooldown_hours": 24,
      "can_vote_now": false
    }
  ]
}

Errors

• 401 Missing or wrong key. {"error":"invalid_key"}
• 403 The demo key is not accepted here. {"error":"demo_key_not_allowed"}
• 429 More than 120 requests a minute. Wait retry_after seconds (also in the Retry-After header). {"error":"rate_limited","retry_after":12}

Parameters

username *	string	Player name.
ip	string	Optional: the address the player connects from, to corroborate a join click. Never returned.

Example request

curl "https://voxelrank.com/api/v1/referral/check?username=Notch" \
  -H "X-Api-Key: YOUR_KEY"

Example response 200

{
  "username": "Notch",
  "eligible": true,
  "reason": "ok",
  "source": "vote",
  "seen_ago": 3400,
  "expires_in": 601400,
  "claimed_at": null,
  "corroborated": false,
  "match": "none",
  "ttl_seconds": 604800,
  "disclaimer": "Confirms the username interacted with your listing here, not that the player followed a link. Treat it as a welcome gift, not proof of origin."
}

Errors

• 401 Missing or wrong key. {"error":"invalid_key"}
• 429 More than 120 requests a minute. Wait retry_after seconds (also in the Retry-After header). {"error":"rate_limited","retry_after":12}

Takes the same filters as the website's own list (copy a filtered list's query string).

Parameters

q	string	Text search.
tag	string	Tag slug.
version	string	Game version.
sort	string	votes (default), players, new, rating, …
page	integer	Page, from 1.
onlineOnly	string	1 for online listings only.

Example request

curl "https://voxelrank.com/api/servers"

Example response 200

{
  "total": 1,
  "page": 1,
  "pages": 1,
  "servers": [
    {
      "id": 8685,
      "name": "Pear SMP",
      "slug": "pear-smp",
      "ip": "play.pearsmp.net",
      "bedrock": null,
      "apply_url": null,
      "version": "1.21.4",
      "country": "US",
      "tags": [
        "survival",
        "smp"
      ],
      "languages": [
        "en"
      ],
      "online": true,
      "players": 47,
      "max_players": 200,
      "motd": "Pear SMP · Season 3",
      "votes_month": 312,
      "votes_total": 4120,
      "tier": 0,
      "url": "https://voxelrank.com/server/8685-pear-smp",
      "vote_url": "https://voxelrank.com/vote/8685-pear-smp",
      "banner": "https://voxelrank.com/banner/pear-smp.svg"
    }
  ]
}

Errors

• 403 Past page 25 without a key. {"error":"key_required_for_page","max_page":25}
• 429 More than 120 requests a minute. Wait retry_after seconds (also in the Retry-After header). {"error":"rate_limited","retry_after":12}

Parameters

slug *

string

Example request

curl "https://voxelrank.com/api/server/pear-smp"

Example response 200

{
  "id": 8685,
  "name": "Pear SMP",
  "slug": "pear-smp",
  "ip": "play.pearsmp.net",
  "bedrock": null,
  "apply_url": null,
  "version": "1.21.4",
  "country": "US",
  "tags": [
    "survival",
    "smp"
  ],
  "languages": [
    "en"
  ],
  "online": true,
  "players": 47,
  "max_players": 200,
  "motd": "Pear SMP · Season 3",
  "votes_month": 312,
  "votes_total": 4120,
  "tier": 0,
  "url": "https://voxelrank.com/server/8685-pear-smp",
  "vote_url": "https://voxelrank.com/vote/8685-pear-smp",
  "banner": "https://voxelrank.com/banner/pear-smp.svg",
  "rank": 12,
  "rating": 4.6
}

Errors

• 404 No such listing. {"error":"not_found"}

Parameters

ids *

string

Comma-separated listing ids.

Example request

curl "https://voxelrank.com/api/servers/status?ids=8685%2C120"

Example response 200

{
  "8685": {
    "online": true,
    "players": 47,
    "max": 200,
    "unreliable": false,
    "unknown": false
  }
}