Public API

Both endpoints accept GET only and return application/json; charset=utf-8. Only public listing data is exposed — owner accounts and email addresses never appear in a response.

/api/servers additionally sends Access-Control-Allow-Origin: * and Cache-Control: public, max-age=60, so it can be called straight from a browser and is safe to cache for a minute. /api/search sends neither and is meant to be called from your own backend.

Base URL: https://minecraftserve.rs

GET /api/servers

The server listing, with the same filters and ordering as the browse page. Only servers with an active listing are returned.

Query parameters

• q — free text, matched against name, tagline and address.
• tag — a single gamemode slug, for example survival. The full list is on the gamemodes page.
• version — major version prefix, for example 1.20, which also matches 1.20.1 and 1.20.4.
• edition — java or bedrock.
• sort — votes (default), players, new, rating or name.
• page — 1-based page number, default 1.
• per — results per page, 1 to 50, default 20.

Unknown values fall back to the default rather than returning an error.

Request

curl "https://minecraftserve.rs/api/servers?tag=survival&sort=players&per=2"

Response

{
  "servers": [
    {
      "name": "The Kingdoms",
      "slug": "the-kingdoms",
      "url": "https://minecraftserve.rs/server/the-kingdoms",
      "host": "play.thekingdoms.net",
      "port": 25565,
      "edition": "java",
      "tagline": "Epic survival with custom quests and player events!",
      "tags": ["survival", "economy", "quests"],
      "version": "1.20.4",
      "motd": "The Kingdoms - Season 4 is live",
      "online": true,
      "players": { "online": 1247, "max": 2000 },
      "votes": { "month": 4210, "total": 51833 },
      "rating": { "average": 4.7, "count": 312 },
      "verified": true,
      "banner": "https://minecraftserve.rs/uploads/9f2c….png",
      "icon": "https://minecraftserve.rs/uploads/1ab7….png",
      "created_at": "2024-11-02 14:08:19"
    }
  ],
  "page": 1,
  "pages": 9,
  "total": 174
}

banner and icon are null when the owner has not uploaded one. version and motd are null until the first successful ping. Timestamps are UTC.

GET /api/search

A narrower endpoint for typeahead and autocomplete: it takes a search term and returns a short list of matches with just enough to render a suggestion row.

Query parameters

• q — the search term. Required, and at least two characters; a shorter or missing term is a 400 rather than an empty list.

There is no page size to set. The endpoint always returns at most eight matches, ordered the same way sort=votes orders the listing, because it exists to fill a suggestion dropdown. Use /api/servers when you need paging or the full record.

Request

curl "https://minecraftserve.rs/api/search?q=kingdom"

Response

{
  "results": [
    {
      "name": "The Kingdoms",
      "slug": "the-kingdoms",
      "tagline": "Epic survival with custom quests and player events!",
      "players": 1247,
      "icon": "/uploads/1ab7….png"
    }
  ]
}

Paths here are site-relative, unlike the absolute URLs in /api/servers. A server with no uploaded icon gets /assets/img/logo-icon.png rather than null, so the field is always safe to put straight into an <img>. Build the page link yourself from slug: https://minecraftserve.rs/server/{slug}.

Errors

Errors come back as {"error": "…"} with the matching status code: 400 for a search term under two characters, 405 for a method other than GET, 404 for an unknown path, 500 if something broke on our side.

Using it fairly

Cache what you fetch and do not poll faster than once a minute — the underlying player counts only change on the ping cycle, so a tighter loop gets you the same numbers. If you are building something that needs more than that, tell us what you need rather than hammering the endpoint.

A link back to the server's page on this site is appreciated but not required.