Free Minecraft status API

Choose an edition

• Java EditionTCP status handshake with SRV resolution, on the default port or an explicit one.
• Bedrock EditionRakNet unconnected ping against the explicit UDP port carried in the target.

One anonymous request

This is a complete request. No key, no signup, no client library.

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

Response shape

{
  "verdict": "online | offline | unknown",
  "observedAt": "2026-07-15T12:00:00.000Z",
  "validUntil": "2026-07-15T12:00:30.000Z",
  "method": "java-status-handshake",
  "evidenceCode": "status_response"
}

verdict

Observation class derived from the canonical evidence code. Do not derive a different state from a nullable latency, player count, or transport error.

evidenceCode

The canonical, stable machine-readable reason for the server verdict. New integrations should branch on this closed code rather than human copy.

unknownReason

Deprecated compatibility copy present only for Unknown server observations. It is derived from evidenceCode, never from a raw exception.

observedAt

RFC 3339 time of the bounded observation.

validUntil

RFC 3339 claim boundary. Past this time, consumers must fail the verdict closed to Unknown until they re-observe.

method

Short identifier for the network action that produced the observation.

Endpoints

The generated OpenAPI 3.1 document is the machine-readable copy of this register.

Limits

Every limited v1 route in the register above draws on one request bucket per caller, sized by the quota class.

A rejected request carries a numeric Retry-After header and runs no outbound probe.

Freshness and errors

Every observation carries freshness, observedAt and validUntil. A stale or missing response is useful history, not a current claim: past validUntil a consumer must fall back to Unknown rather than repeating the last verdict. Do not poll a target faster than its returned validity window.

Handle 400 for an invalid request, 401 for a malformed or revoked bearer key, 429 for a spent budget, and 503 when the service cannot complete the bounded work. A 202 is a short-lived pending receipt: poll the URL it returns instead of starting a second observation.

Cross-origin requests

Public routes answer Access-Control-Allow-Origin: *, so a browser client can call them directly. The v1 routes also accept Authorization in preflight; the unversioned routes accept Content-Type only. Per-caller responses are private, no-store and carry X-Robots-Tag: noindex. The OpenAPI document and the status badges are the publicly cacheable exceptions.

A key belongs on your server, never in browser JavaScript: an anonymous browser request already has the anonymous allowance, and a key shipped to a page is a key given away.

Attribution

Keep a visible credit wherever a reading from this API is displayed. The credit link may be rel="nofollow"; the visible text is what matters.

<a href="https://minecraftstatus.com/server/play.example.net" rel="nofollow">
  Status by MinecraftStatus.com
</a>

Examples by language

Each example is a runnable program with the same failure handling: status first, then freshness, then the fields.

• cURL
• JavaScript
• TypeScript
• Python
• PHP
• Java

API keys

A free developer account raises the allowance and nothing else: the same routes, the same contract, the same evidence. Keys are shown once, hashed at rest, and individually revocable.

Create or manage a developer key · Read the documentation