# mcstatus API — agent guide

REST API for Minecraft server status (Java and Bedrock). JSON, no authentication.
Base: https://api.mcstatus.streetworks.com.br

## Endpoints

GET /v1/status/{address}   — detects the edition automatically (Java and Bedrock in parallel). Use this by default.
GET /v1/java/{address}     — Java status (modern SLP + legacy 1.6/beta fallback)
GET /v1/bedrock/{address}  — Bedrock status (RakNet)
GET /v1/query/{address}    — GS4 Query: named player list, plugins, map. Only works if the server has enable-query=true (most don't; treat "enabled": false as normal)
GET /v1/simple/{address}   — plain text "online" (HTTP 200) or "offline" (HTTP 404); ideal for health checks
GET /v1/icon/{address}     — server favicon as binary PNG
GET /v1/banner/{address}[.png|.svg] — embeddable image (see Banner below)
GET /v1/badge/{address}    — shields.io-style SVG badge (?metric=players|status|ping)
GET /v1/protocol/{q}       — maps protocol↔version: accepts a number (769), a version (1.21.4) or "all" (full table)
POST /v1/snapshot          — freeze the current lookup and get a permanent shareable URL (see Snapshots below)
GET /v1/snapshot/{edition}/{address}?time={stamp} — read a frozen lookup back

{address} = host or host:port. Without a port, the _minecraft._tcp SRV record is followed (like the official client).

## Field selection (recommended to save tokens)

Every JSON route accepts ?fields= with dot-notation, or exclusion with a "-" prefix:
  /v1/status/hypixel.net?fields=online,players.online,version.name_clean,motd.clean
  /v1/status/hypixel.net?fields=-icon        (icon is heavy base64; exclude it if unused)

## Response shape (online)

{
  "online": true, "edition": "java"|"bedrock",
  "hostname": str, "ip": str, "port": int,
  "version": { "name_clean": str, "protocol": int },
  "players": { "online": int, "max": int, "list": [{uuid,name_clean,...}] },
  "motd": { "raw": str, "clean": str, "html": str, "ansi": str },
  "icon": "data:image/png;base64,..."|null,
  "mods": [...], "software": str|null, "gamemode": str|null (bedrock),
  "srv_record": {host,port}|null,
  "dns_records": [{name,type:"SRV"|"CNAME"|"A"|"AAAA",data}],
  "eula_blocked": bool (official Mojang blocklist),
  "latency": int|null (ms),
  "retrieved_at": epoch_ms, "expires_at": epoch_ms
}

Offline: { "online": false, "error": "dns_nxdomain"|"dns_no_records"|"timeout"|"refused", "eula_blocked": bool, ... }
Malformed address: HTTP 400 { "error": "invalid_address" }. Unknown route: HTTP 404.

## Banner (embeddable images)

/v1/banner/{address}.png?style=pixel&theme=dark&scale=2
Params: style=minimal|swiss|pixel|neo · theme=dark|light|mono · layout=wide|compact
        accent/bg/fg=hex without # · radius=0-24 · hide=motd,icon,players,version,ping,address
        label=text · scale=2 (retina) · edition=auto|java|bedrock
Use .png for Discord (doesn't render SVG); SVG (default) for GitHub/web.

## Snapshots (frozen lookups)

A snapshot stores one lookup exactly as it was, behind a permanent URL. Useful to cite
"the server looked like this at that moment" instead of a number that changes every minute.

Create:  POST /v1/snapshot   Content-Type: application/json   Body: {"address":"mc.example.com","edition":"java"}
Returns: {"address","edition","time":"20260901T142305Z","at":epoch_ms,"url","created":bool}

Read:    GET /v1/snapshot/java/mc.example.com?time=20260901T142305Z
Returns: {"address","edition","time","at","status":{...same shape as /v1/status...}}
         HTTP 404 {"error":"snapshot_not_found"} if that stamp was never saved.

- "time" is the UTC instant the data was COLLECTED (basic ISO-8601, YYYYMMDDThhmmssZ), not the moment of the request.
  Saving the same cached data twice returns the same URL and writes nothing new.
- You cannot save a snapshot for an arbitrary past instant: the API only ever stores what it just fetched itself.
- Snapshots are immutable and kept for 1 year, renewed whenever they are read.
- Writes are rate limited to 10 req/60s per IP (tighter than the read routes).
- ?fields= works on the read route and filters inside "status".
- The human-facing URL is https://mcstatus.streethosting.com.br/lookup?server={address}&time={stamp}

## Rules for agents

- Caching: responses are cached for 60s per address; retrieved_at/expires_at expose the window. Don't repeat the same query within 60s expecting fresh data.
- Rate limits per IP: 60 req/10s (JSON), 15 req/10s (banner/badge), 10 req/60s (POST /v1/snapshot). On HTTP 429, wait for the retry-after header value before retrying.
- Prefer ?fields= with the minimum you need.
- "online": false with "error": "timeout"/"refused" means the server is down or unreachable — it is not an API error; don't retry immediately.
- Latency and player counts naturally vary between queries.