MinecraftStatus
Documentation

Check Minecraft status with cURL

Copy this example, set an optional MINECRAFTSTATUS_API_KEY in the environment, and pass an edition plus address. The example preserves pending, quota and freshness boundaries.

Source

cURL · anonymous by default
#!/usr/bin/env bash
set -euo pipefail

base="${MINECRAFTSTATUS_API_BASE:-https://minecraftstatus.com}"
edition="${1:-java}"
address="${2:-play.example.net}"
key="${MINECRAFTSTATUS_API_KEY:-}"
auth=()
if [[ -n "$key" ]]; then auth=(-H "Authorization: Bearer $key"); fi

tmp="$(mktemp)"
trap 'rm -f "$tmp"' EXIT
encoded="$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$address")"
status="$(curl --silent --show-error --output "$tmp" --write-out '%{http_code}' \
  -H 'Accept: application/json' "${auth[@]}" \
  "$base/api/v1/status/$edition?address=$encoded")"

if [[ "$status" == "429" ]]; then
  echo "rate limited; retry after the Retry-After response header" >&2
  cat "$tmp"
  exit 75
fi
if [[ "$status" == "202" ]]; then
  echo "observation pending; poll the returned pollUrl without spending another target unit"
  cat "$tmp"
  exit 0
fi
if [[ "$status" -ge 400 ]]; then
  echo "API request failed with HTTP $status" >&2
  cat "$tmp" >&2
  exit 1
fi

python3 - "$tmp" <<'PY'
import json, sys
body = json.load(open(sys.argv[1], encoding="utf-8"))
print(json.dumps(body, indent=2))
if body.get("freshness") in {"stale", "missing"}:
    print("status claim is not current; schedule a new observation", file=sys.stderr)
PY

Run with an address argument such as java play.example.net. The source files are versioned alongside this documentation under examples/api/curl/status.sh.

Choose another language

Contract boundary

Every example branches on HTTP status first, prints a queued job receipt for 202, respects Retry-After for 429, and refuses to present stale or missing freshness as current.