01
Começando
Uma chamada, sem chave de API. Passe o endereço do servidor e receba tudo em JSON.
curl https://api.mcstatus.streetworks.com.br/v1/status/hypixel.net?fields=online,players.online
{"online":true,"edition":"java","players":{"online":31868}}:addresshost ou host:porta. Sem porta, o SRV _minecraft._tcp é seguido — o mesmo comportamento do cliente oficial.
?fields=dot-notation para receber só o necessário (players.online,motd.clean), ou exclusão com ‑ (-icon tira o favicon, o campo mais pesado). Funciona em todas as rotas JSON.
02
Endpoints
Status
GET/v1/status/:addressdetecção automática Java/Bedrock — use este por padrão
GET/v1/java/:addressJava (todas as versões, do beta ao atual)
GET/v1/bedrock/:addressBedrock
GET/v1/simple/:address"online" (200) / "offline" (404) em texto — uptime checks
Dados extras
GET/v1/query/:addressQuery GS4: jogadores nominais, plugins, mapa (requer enable-query no servidor)
GET/v1/protocol/:queryprotocolo ↔ versão: 769, 1.21.4 ou "all"
GETPOST /v1/snapshotcongela o lookup atual e devolve uma URL permanente para compartilhar
GET/v1/snapshot/:edition/:address?time=lê um lookup congelado; o carimbo é o instante da coleta (AAAAMMDDTHHMMSSZ, UTC)
Imagens
GET/v1/banner/:address[.png]banner embutível — ver seção abaixo
GET/v1/badge/:addressbadge estilo shields.io
GET/v1/icon/:addressfavicon do servidor em PNG
03
Resposta
Campos do JSON de status. Offline traz online: false com o motivo em error.
online · errorestado; erros: dns_nxdomain (domínio não existe), dns_no_records, timeout, refused
ip · port · hostnameendereço resolvido
version · playersversão (nome + protocolo) e contagem/amostra de jogadores
motd4 formatos: raw (§-codes), clean (texto puro), html, ansi
icon · mods · softwarefavicon base64, mods Forge, software detectado (Paper, Velocity…)
srv_record · dns_recordsSRV seguido e a cadeia completa de resolução (SRV → CNAME → A)
eula_blockedbloqueado pela Mojang — checagem real contra a blocklist oficial
latency · retrieved_at · expires_atRTT em ms e a janela de cache do dado
04
Banner & badge
Imagens prontas para README, fórum e Discord. SVG por padrão; .png onde SVG não renderiza (Discord).
Parâmetros do banner
styleminimal (padrão) · swiss · pixel · neo — linguagem visual
themedark (padrão) · light · mono — paleta
layoutwide 728×110 (padrão) · compact 400×64
accent · bg · fgcores hex sem # — sobrepõem o theme
radiuscantos, 0–24 (padrão vem do style)
hidecsv para omitir: motd,icon,players,version,ping,address
labeltexto no lugar do endereço (máx. 32)
scale · editionscale=2 para PNG retina · edition=auto|java|bedrock
Parâmetros do badge
https://api.mcstatus.streetworks.com.br/v1/badge/hypixel.net?metric=players&style=flat-square
metricplayers (padrão) · status · ping
label · colortexto da esquerda · hex da direita
styleflat (padrão) · flat-square
O MOTD mantém as cores originais do servidor. Embutir a mesma URL em vários lugares não gera pings extras — a imagem é cacheada.
05
Limites & cache
Limites por IP. Ao exceder: 429 com header retry-after. Para alto volume, fale com a StreetHosting.
rotas JSON60 requisições / 10s
banner · badge15 requisições / 10s — geração de imagem custa mais
cache de status60s por endereço, com stale-while-revalidate: resposta instantânea, revalidação em segundo plano
cache de imagensSVG 300s · PNG 600s · offline 60s