Vote API

Basics

• Responses are JSON. Send the header Accept: application/json with every request.
• No authentication is required.
• Limit: 30 requests per minute per IP address.
• All times are in UTC.
• A player can vote for a server once a day, and a server can receive at most 30 votes a day.

Your server's UUID

Every listed server has a permanent UUID that identifies it in the API, so it keeps working even if the server's address changes. The UUID is shown to owners on the server page. If you can't find it, contact us with your server address and we'll send it to you.

List votes

GET https://mcserverscout.com/api/servers/{uuid}/votes

Returns votes for the server, newest first. Anonymous votes (without a nickname) are not included.

Query parameters

All parameters are optional.

Example request

curl -H "Accept: application/json" \
  "https://mcserverscout.com/api/servers/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/votes?nick=Steve&date_from=2026-10-23"

Example response

{
  "data": [
    {
      "nick": "Steve",
      "created_at": "2026-10-23T14:30:00+00:00"
    }
  ],
  "links": {
    "first": "https://mcserverscout.com/api/servers/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/votes?page=1",
    "last": "https://mcserverscout.com/api/servers/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/votes?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "per_page": 100,
    "to": 1,
    "total": 1
  }
}

Use links.next or the page parameter to fetch further pages. The meta object also contains the standard pagination fields path and links.

Errors

• 404: no server with this UUID. Check that you copied the whole UUID.
• 422: a parameter is invalid, for example limit=500. The response's errors object names the parameter and what's wrong with it.
• 429: more than 30 requests in a minute. Wait for the time given in the Retry-After header.

Rewarding votes in a plugin

The simplest approach: when a player runs a command such as /vote claim, ask the API whether that nickname voted today, and give the reward if it did and hasn't been claimed yet. Store the claimed date per player so a vote can't be redeemed twice.

A minimal check for a Paper or Spigot plugin (Java 11+), run off the main thread:

// Returns true if the player has voted today (UTC).
CompletableFuture<Boolean> hasVotedToday(String nick) {
    String today = LocalDate.now(ZoneOffset.UTC).toString();
    URI uri = URI.create(API_URL
        + "?limit=1&date_from=" + today
        + "&nick=" + URLEncoder.encode(nick, StandardCharsets.UTF_8));

    HttpRequest request = HttpRequest.newBuilder(uri)
        .header("Accept", "application/json")
        .build();

    return HttpClient.newHttpClient()
        .sendAsync(request, HttpResponse.BodyHandlers.ofString())
        .thenApply(response -> response.statusCode() == 200
            && !response.body().contains("\"data\":[]"));
}

Set API_URL to https://mcserverscout.com/api/servers/{uuid}/votes with your server's UUID. Give the reward back on the main thread, for example with Bukkit.getScheduler().runTask(...). If you'd rather reward players automatically, poll the API every few minutes with date_from set to today and process nicknames you haven't seen yet. Stay well under the 30 requests per minute limit.