Minecraft server status API: fields, caching, and evidence windows

Treat each response as bounded evidence, branch on the canonical evidenceCode, and turn expired or ambiguous results into Unknown.

Last verified

2026-07-21

Evidence cutoff

2026-07-21

Direct answer: evidenceCode is the canonical machine-readable meaning of a server observation. verdict is the closed display class derived from that code. Keep observedAt and validUntil with the result, and after validUntil show Unknown until fresh evidence arrives. Latency, player counts, MOTD text, and unknownReason do not override that rule.

This page describes the public MinecraftStatus API as reviewed on 2026-07-21. The field tables below follow the same response shapes served by the API; when a contract changes, the live API protocol sheet is the current reference.

Public endpoint register and limits

The API protocol sheet and the response examples below use the same endpoint register.

Use the interactive checker when a person needs the same server observation with interpretation rather than raw JSON.

Java and Bedrock consume one shared server-probe budget. A server-route 429 means no outbound check ran for that rejected request; it does not mean the target server is Offline. /api/services, /api/health, and the community heartbeat read local state on the request path rather than probing an upstream service.

Server evidence fields

Every successful Java or Bedrock server response includes these common fields:

The closed server evidence mapping is:

Only connection_refused from an admitted target means Offline. Silence, timeouts, resets, malformed data, DNS ambiguity, capacity limits, and internal failures remain Unknown. unknownReason is display copy, not a second taxonomy.

Java response shape

Java adds:

{
  "verdict": "online",
  "evidenceCode": "status_response",
  "host": "java.example",
  "port": 25565,
  "latency": 42,
  "observedAt": "2026-07-21T12:00:00.000Z",
  "validUntil": "2026-07-21T12:00:30.000Z",
  "method": "java-status-handshake",
  "version": { "name": "1.21.8", "protocol": 772 },
  "players": { "online": 12, "max": 100, "sample": [] },
  "motd": { "raw": "Contract fixture", "clean": "Contract fixture", "html": "Contract fixture" },
  "favicon": null
}

The version, player, MOTD, and favicon values are server advertisements. Read the Java status response guide before presenting them as more than that.

Bedrock response shape

Bedrock has the same common evidence fields, version object, player object, and MOTD forms. It adds gamemode and serverId; it does not include the Java favicon field.

{
  "verdict": "online",
  "evidenceCode": "status_response",
  "host": "bedrock.example",
  "port": 19132,
  "latency": 42,
  "observedAt": "2026-07-21T12:00:00.000Z",
  "validUntil": "2026-07-21T12:00:30.000Z",
  "method": "bedrock-raknet-unconnected-ping",
  "version": { "name": "1.21.100", "protocol": 776 },
  "players": { "online": 12, "max": 100, "sample": [] },
  "motd": { "raw": "Contract fixture", "clean": "Contract fixture", "html": "Contract fixture" },
  "gamemode": "Survival",
  "serverId": "123456789"
}

Caching and validUntil

Apply these rules in order:

1. Cache the complete observation, including evidenceCode, observedAt, and validUntil.

2. While the evidence window is current, branch on evidenceCode or the derived verdict.

3. After validUntil, treat Online, Offline, and every other prior state as Unknown until a fresh response arrives.

4. Do not poll faster than the returned evidence window. Repeated callers can share one bounded cache entry and one in-flight check.

5. Keep edition and address identity in the cache key. Java and Bedrock are different protocols even though they share a client quota.

6. Treat 429, capacity failure, malformed timestamps, and failed refreshes as Unknown—not Offline and not proof of an outage.

The Online, Offline, and Unknown guide covers the display meaning. The latency guide explains why a status round trip is not gameplay tick performance.

HTTP response policy

Successful server and service responses emit X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Rejected quota requests emit Retry-After; these headers describe the client budget and never change a target verdict.

Local health and community response shapes

/api/health uses the response shape below. The live release, uptime, and time values change at runtime.

{
  "schemaVersion": 2,
  "contract": "minecraftstatus-health/v2",
  "status": "ok",
  "domain": "minecraftstatus.com",
  "service": "minecraftstatus",
  "release": "contract-fixture",
  "uptimeSeconds": 42,
  "time": "2026-07-21T12:00:00.000Z",
  "components": {
    "website": { "status": "online", "release": "contract-fixture" },
    "discordBot": { "status": "unknown", "release": null, "observedAt": null }
  }
}

/api/v1/community/status fails closed to this private, no-store Unknown envelope when no admitted local heartbeat exists:

{
  "schemaVersion": 1,
  "contract": "minecraftstatus-community-status/v1",
  "status": "unknown",
  "release": null,
  "observedAt": null,
  "validUntil": null
}

/api/services: 13 scoped rows

/api/services returns minecraftstatus-service-view/v2 with snapshotStatus, generatedAt, validUntil, and exactly 13 ordered components. Each component exposes id, label, sourceKind, outcome, state, evidenceCode, timestamps, latency, evidence scope, limitation, and an optional reference URL.

Four evidence sources are enabled:

The other 9 explicit not-collected rows return state: "not-collected", outcome: "not-collected", and evidenceCode: "collector_disabled" with null observation timestamps:

Anonymous synthetic failures stay Unknown. They cannot publish degraded or outage. Only the official PlayFab row can provide a scoped degraded or outage state, and that state describes the official PlayFab report within the row's stated scope. The services array is not an overall Minecraft health verdict, and clients must not aggregate it into one.

If the local service snapshot is missing, invalid, stale, or belongs to another release, enabled rows fail closed to Unknown while disabled rows remain explicitly not collected.

Integration checklist

1. Call the endpoint for the correct edition and retain the address form used for the request.

2. Branch server UI on canonical evidenceCode; use verdict as its closed display class.

3. Store and display observedAt and validUntil beside any status badge.

4. Replace expired evidence with Unknown before rendering or alerting.

5. Treat service rows independently and retain each row's evidenceScope and limitation.

6. Respect the shared 20-per-60-second server budget and the 60-per-60-second services budget.

7. Keep private resolution and connect targets out of logs and public responses.

Contract version

This guide covers contract version 1, reviewed on 2026-07-21. Use the live API protocol sheet for current endpoint schemas and limits.

Related reading

• API protocol sheet

• MOTD and Java status response

• Online, Offline, and Unknown