ServerRoamSign inSubmit serverSubmit server

Public API

List servers, read live player counts and votes, or show a server on your own site. Read-only JSON over HTTPS, no key needed.

Basics

The base URL is https://serverroam.com/api/v1. Every endpoint answers GET with JSON, needs no key and no account, and sends Access-Control-Allow-Origin: *, so a browser can call it from any site.

Responses are cached for 30 seconds (Cache-Control: public, max-age=30), so asking more often returns the same data. There is no per-client quota in the API itself. Please cache on your side and do not poll faster than that.

Listings are the ones shown on the site: published and seen online within the last 7 days. votes counts the last 30 days.

Games

GET /games returns the supported games. servers is the list URL for that game.

curl
curl https://serverroam.com/api/v1/games
Response
{
  "data": [
    {
      "slug": "minecraft",
      "name": "Minecraft",
      "url": "https://serverroam.com/minecraft",
      "servers": "https://serverroam.com/api/v1/servers?game=minecraft"
    }
  ]
}

List servers

GET /servers returns one page of listings. All parameters are optional:

game is a game slug from /games, for example minecraft, fivem or redm. Without it, all games are listed. An unknown slug answers 400 unknown_game.

tag limits the list to servers with that tag, for example survival or roleplay. It is case-insensitive; a malformed one answers 400 invalid_tag.

country limits the list to servers in one country, as a two-letter ISO 3166 code such as de or us. A malformed one answers 400 invalid_country.

q is a search in the server name: a case-insensitive substring, at most 60 characters.

sort is top (most votes, then most players; the default), players (most players online) or new (newest listing first). Any other value falls back to top.

page starts at 1 and may go up to 400; anything else is page 1. A page holds 50 servers. hasMore says whether another page follows. There is no total count.

curl
curl "https://serverroam.com/api/v1/servers?game=minecraft&tag=survival&sort=players&page=1"
curl "https://serverroam.com/api/v1/servers?q=roleplay&sort=new"
Response
{
  "data": [
    {
      "id": 42,
      "game": "minecraft",
      "name": "Example SMP",
      "description": "A friendly survival server.",
      "url": "https://serverroam.com/minecraft/example-smp",
      "connect": "play.example.com",
      "icon": "https://serverroam.com/icons/42",
      "online": true,
      "players": 37,
      "maxPlayers": 100,
      "votes": 214,
      "verified": true,
      "version": "1.21.4",
      "map": null,
      "country": null,
      "tags": ["survival", "smp"],
      "listedAt": "2026-10-02T09:15:00.000Z"
    }
  ],
  "page": 1,
  "hasMore": true
}

Server fields

id is a number that stays the same. game is the game slug. name and description are the listing text. url is the server's page on this site: send players there to vote.

connect is what a player pastes into the game: the address on Minecraft, connect cfx.re/join/<code> on FiveM and RedM. icon is an absolute image URL, or null.

online is the result of the last status check, players and maxPlayers the player count and slots. votes are the votes of the last 30 days. verified is true once the owner has claimed the server.

version, map and country are null where the game does not report them. tags is a list of lowercase tags. listedAt is when the server was added, as an ISO 8601 time in UTC.

One server

GET /servers/{game}/{slug} returns one server in data. The slug is the last part of the listing's address on this site. Servers that are not listed answer 404 not_found.

The single-server response has one more field, history: peak24h and peak7d are the highest player counts of the last 24 hours and 7 days, avg7d is the average of the hourly peaks and uptime7d is the share of status checks in which the server answered, in percent. history is null until a server has at least two hours of data.

curl
curl https://serverroam.com/api/v1/servers/minecraft/example-smp
Response
{
  "data": {
    "id": 42,
    "...": "the fields above",
    "history": { "peak24h": 61, "peak7d": 74, "avg7d": 33, "uptime7d": 99 }
  }
}

Errors

Errors come with an HTTP status and a body like the one below. Error responses are cached for 30 seconds as well. The codes are unknown_game and invalid_tag (both 400) and not_found (404).

400
{ "error": "unknown_game" }

JavaScript

fetch
const res = await fetch("https://serverroam.com/api/v1/servers?game=fivem&sort=top");
const { data, hasMore } = await res.json();
for (const server of data) console.log(server.name, server.players, server.votes);

More for your site

Show a vote badge with the badge, and receive votes on your server with webhooks or Votifier.