Java server status API

Request

curl --fail-with-body \
  -H 'Accept: application/json' \
  'https://minecraftstatus.com/api/v1/status/java?address=play.example.net:25565'

address accepts a hostname or IP with an optional port. If the port is omitted, the Java default is 25565 and SRV resolution is part of the canonical target resolution. Use the SRV and custom-port guide when the published address is not the wire endpoint.

Read the response

{
  "contract": "minecraftstatus-observation/v1",
  "target": { "edition": "java", "address": "play.example.net", "port": 25565 },
  "verdict": "online",
  "evidenceCode": "status_response",
  "observedAt": "2026-09-20T12:00:00.000Z",
  "validUntil": "2026-09-20T12:03:00.000Z",
  "freshness": "fresh",
  "players": { "online": 12, "max": 100, "source": "server-reported" },
  "version": { "reportedName": "1.21.8", "protocol": 772 },
  "latencyMs": 42
}

• Player countServer-reported values can be null and never prove joinability.
• MOTDUse sanitized parts when rendering formatting.
• Reported versionStatus response evidence is not compatibility proof.

Failure and freshness

Handle 400 for an invalid request, 401 for a malformed or revoked bearer key, 429 with the numeric Retry-After header, and 503 when the API infrastructure cannot complete the request. A successful response may still have freshness: "stale" or "missing"; branch on the freshness and evidence fields rather than latency or player count.