Declare your fleet, get a measured uptime figure

Why you need to tell us

We identify a server's host from reverse DNS and who owns its IP range. That works for companies on their own hardware, but a host renting from a datacenter shows up under the datacenter's name, so we can't see your customers unless you tell us which servers they are.

Getting access

Email contact@minecraft-java-servers.com and we'll issue an API key tied to your company. It's free, and the key can only change your own list.

The list

A plain text file, one server per line, using the address players type into Minecraft to join.

play.example.com
pvp.example.net:25566        # port only if it isn't 25565
198.51.100.42
bigsmp.example.org, USA East # anything after the address is ignored

Blank lines are ignored, and so is anything after a #. If players join with just a hostname, leave the port off and we'll follow the SRV record like the game does.

Optional: listing details

We already read each server's name, description, version and game modes from its own status response, so you don't need to send these. If you want to, add a header row naming the columns:

address,name,description,website,discord,country,types
play.example.com,Example SMP,"Vanilla survival since 2019 with weekly build events, an active staff team, player shops and a friendly community.",https://example.com,https://discord.gg/example,DE,"Survival,SMP"

Column order doesn't matter and unknown columns are ignored. The header is required for this; without one, everything after the address is ignored so a note like "USA East" can't end up as a server's name.

These only fill in blanks. They're applied to unclaimed listings where that detail is empty or a default MOTD, and never overwrite anything a customer has set on a listing they've claimed. A value that breaks a rule is skipped and reported, without failing the rest of the list. Vote-reward (Votifier) settings aren't accepted, since those belong to the server owner.

JSON

Works for everything, and is the only way to send banners and icons (as base64):

{"servers": [
  "pvp.example.net:25566",
  {"host": "play.example.com", "name": "Example SMP",
   "types": ["Survival", "SMP"],
   "banner": "iVBORw0KGgo...", "icon": "data:image/png;base64,iVBORw0KGgo..."}
]}

Sending it

curl -X POST -H "X-API-Key: YOUR_KEY" \
     --data-binary @fleet.txt https://minecraft-java-servers.com/api/v1/fleet

A GET to the same URL with your key shows what we have under your name without changing anything. There's no need to sync more than once a day.

Each list replaces the last

Send your full current list every time. Servers missing from it are removed from your name, which is how we know a customer has left; otherwise old servers would keep counting toward your figure.

Public or private

Chosen when your key is issued.

The servers belong to your customers, so if any of them would rather not be listed, tell us and we'll remove them.

Response

{
  "provider":         "Example Host",
  "submitted":        42,
  "newly_tagged":     7,
  "already_tagged":   33,
  "released":         2,
  "queued_for_add":   0,
  "not_responding":   ["old.example.com"],
  "fields_applied":   3,
  "field_warnings":   [{"address": "play.example.com",
                        "field": "website", "reason": "not a valid URL"}],
  "total_attributed": 40,
  "total_online":     38,
  "visibility":       "public — listed in the directory"
}

If released is ever higher than you expect, your export has probably changed.

When figures appear

We publish what we measure, good or bad. Servers that are switched off or abandoned aren't counted against you; the report explains how.

Errors

Questions

Email contact@minecraft-java-servers.com. If you're building something with our data rather than submitting servers, see the public API docs.