MCBoxes - Minecraft Server Status Checker

Standard Status

Use standard mode when you want one clean answer from the controller itself. This is the simplest endpoint for websites, bots, and routine checks.

GET/v1/status/:server?type=java

Resolves SRV records for Java, performs one direct status ping, and returns normalized DNS and server details.

Use `type=java` for Java Edition servers.
Use `type=bedrock` for Bedrock Edition servers.
If no port is provided, Java defaults to `25565` and Bedrock to `19132`.

Example/v1/status/mc.hypixel.net?type=java

{
  "online": true,
  "host": "mc.hypixel.net",
  "port": 25565,
  "latency": 703,
  "version": {
    "name": "Requires MC 1.8 / 1.21",
    "name_clean": "1.8",
    "protocol": 767
  }
}

Distributed Status

Use distributed mode when network location matters. Each connected probe checks the same target and reports back under its own node id and region label.

GET/v1/distributed/:server?type=java

Returns `target`, `result_count`, and `nodes`.
Each node includes its `node_region` and a normalized `status` object.
Displayed DNS chains are kept consistent with the controller view.

Example/v1/distributed/mc.wynncraft.com?type=java

{
  "target": "mc.wynncraft.com",
  "result_count": 1,
  "nodes": {
    "local-01": {
      "node_region": "Local",
      "status": {
        "online": true,
        "latency": 447
      }
    }
  }
}

Health Endpoints

Health checks are intentionally split into a public liveness route and a restricted observability route.

Route	Purpose	Access
`/health`	Minimal uptime signal for load balancers and public monitoring.	Public
`/health/details`	Probe inventory, pending task count, task metrics, and recent errors.	Restricted by `HEALTH_DETAILS_WHITELIST`

Response Shape

Standard and distributed mode now share the same formatting rules for core status objects. That means API consumers can parse the same field names and content conventions in both modes.

Field	Meaning	Notes
`online`	Server ping result	`false` when DNS lookup fails, connection times out, or ping parsing fails.
`latency`	Round-trip time in milliseconds	Available for successful Java and Bedrock responses.
`ip_info`	Resolved IP data and DNS chain	May include `ip`, `ips`, `srv_record`, `asn`, `location`, `dns_records`.
`version`	Reported Minecraft version block	`name_clean` is normalized to a stable value like `1.8` or `1.26.10`.
`players`	Online player counts	Empty player sample arrays are stripped so consumers do not need to special-case them.
`motd`	Raw, clean, and HTML-formatted description	HTML output is normalized for consistent styling across both modes.

Errors & Limits

The API returns structured HTTP status codes and plain JSON error payloads. Plan for controller-side rate limiting and user input mistakes.

Common error responses

400 Missing or invalid `type` parameter.
403 `/health/details` requested from a non-whitelisted IP.
429 Rate limit reached for the current scope.
503 No connected probe nodes are available for distributed mode.

Headers to watch

X-RateLimit-Limit total quota for the active window.
X-RateLimit-Remaining requests left before throttling.
Retry-After seconds to wait after a `429`.