Skip to main content
Command Block Front

Developer API

Free REST API for Minecraft server status, badges, and embeddable widgets.

No API Key Needed Free Forever REST + JSON

Overview

The ServerHub API provides free access to Minecraft server data. Use it to build Discord bots, website widgets, monitoring tools, or anything else you can imagine.

Status API

Ping any server

Badge API

Dynamic SVG/PNG badges

Widgets

Embeddable live widgets

Base URL

All API endpoints use the base URL: https://minecraft-serverhub.com

Server Status API

GET/api/ping?host={host}&port={port}&platform={platform}

Ping a Minecraft server to check its online status, player count, version, and MOTD.

ParameterTypeRequiredDescription
hoststringRequiredServer hostname or IP address (e.g., play.hypixel.net)
portnumberOptionalServer port. Defaults to 25565 (Java) or 19132 (Bedrock)
platformstringOptional"java" or "bedrock". Defaults to "java"

Response

200 OKjson
{
  "online": true,
  "players": { "online": 42, "max": 100 },
  "version": "1.21.4",
  "motd": "Welcome to my server!",
  "favicon": "data:image/png;base64,...",
  "ping": 45,
  "error": null
}

Code Examples

JavaScript (fetch)javascript
const response = await fetch(
  'https://minecraft-serverhub.com/api/ping?host=play.hypixel.net'
);
const data = await response.json();

if (data.online) {
  console.log(`Server is online with ${data.players.online} players`);
} else {
  console.log('Server is offline');
}
Python (requests)python
import requests

response = requests.get(
    'https://minecraft-serverhub.com/api/ping',
    params={'host': 'play.hypixel.net', 'platform': 'java'}
)
data = response.json()

if data['online']:
    print(f"Online: {data['players']['online']}/{data['players']['max']}")
else:
    print("Server is offline")
cURLbash
curl "https://minecraft-serverhub.com/api/ping?host=play.hypixel.net&platform=java"

Badge API

Dynamic badges that show your server's live status. Perfect for README files, forum signatures, and websites.

GET/api/badges/{slug}/svg?style={style}

Returns a dynamic SVG badge showing server name, player count, and online status.

ParameterTypeRequiredDescription
slugstringRequiredServer slug from the server's ServerHub URL
stylestringOptional"flat" (default), "flat-square", or "for-the-badge"
GET/api/badges/{slug}/png?style={style}

Same as SVG but returns a PNG image. Useful for platforms that don't support SVG.

Badge Styles

flat
ServerHub
42/100
flat-square
ServerHub
42/100
for-the-badge
ServerHub
42/100

Embed Code

HTMLhtml
<!-- Replace 'your-server' with your server's slug -->
<a href="https://minecraft-serverhub.com/servers/your-server">
  <img src="https://minecraft-serverhub.com/api/badges/your-server/svg"
       alt="Server Status" />
</a>
Markdown (for GitHub, etc.)markdown
[![Server Status](https://minecraft-serverhub.com/api/badges/your-server/svg)](https://minecraft-serverhub.com/servers/your-server)
BBCode (for forums)bbcode
[url=https://minecraft-serverhub.com/servers/your-server]
[img]https://minecraft-serverhub.com/api/badges/your-server/png[/img]
[/url]

Embeddable Widgets

Embed a live server status widget on your website. The widget updates automatically every 60 seconds and shows your server's real-time status, player count, and more.

GET/api/widgets/{slug}?theme={theme}&size={size}

Returns a complete HTML page for use in an iframe. Shows live server status with auto-refresh.

ParameterTypeRequiredDescription
slugstringRequiredServer slug from your ServerHub URL
themestringOptional"dark" (default), "light", or "transparent"
sizestringOptional"compact" (~40px), "standard" (~80px, default), or "full" (~120px)

Embed Code

Standard Widget (recommended)html
<!-- Replace 'your-server' with your server's slug -->
<iframe
  src="https://minecraft-serverhub.com/api/widgets/your-server?theme=dark&size=standard"
  width="300"
  height="90"
  frameborder="0"
  style="border: none; border-radius: 8px;"
></iframe>
Compact Widgethtml
<iframe
  src="https://minecraft-serverhub.com/api/widgets/your-server?theme=dark&size=compact"
  width="280"
  height="50"
  frameborder="0"
  style="border: none;"
></iframe>

Theme Options

My Server
42/100 players
dark
My Server
42/100 players
light
My Server
42/100 players
transparent

Pro Tip

The widget automatically updates every 60 seconds. The "View on ServerHub" link at the bottom helps players find your full server page with reviews, vote links, and more details.

Rate Limits & Best Practices

EndpointRate LimitCache TTL
/api/ping60 req/minNone (live)
/api/badges/*/svg120 req/min5 minutes (Redis)
/api/badges/*/png120 req/min5 minutes (Redis)
/api/widgets/*60 req/min5 minutes

Best Practices

  • Cache responses for at least 60 seconds in your application to minimize API calls.
  • Handle errors gracefully. Servers may go offline or timeout. Always check the online field.
  • Use the correct platform. Java and Bedrock use different protocols. Sending a Java ping to a Bedrock server will fail.
  • Set a User-Agent header in your requests so we can identify your application if there are issues.

Frequently Asked Questions

Is the API free to use?
Yes, the ServerHub API is completely free for personal and commercial use. We don't require API keys or authentication for public endpoints.
What are the rate limits?
Public endpoints have a generous rate limit of 60 requests per minute per IP address. This is more than enough for most use cases. If you need higher limits, contact us.
Can I use the API in my Discord bot?
Absolutely! The Status API is perfect for Discord bots. You can ping any server and display the status in your bot. Just make sure to cache results for at least 60 seconds to stay within rate limits.
Do badges count as backlinks?
Badge images themselves are not links, but the standard embed code wraps them in an <a> tag that links back to the server's page on ServerHub. This is a natural attribution link.
Can I customize the widget appearance?
Yes! Widgets support 3 themes (dark, light, transparent) and 3 sizes (compact, standard, full). You can mix and match to fit your website's design.
Is there a WebSocket or real-time API?
Currently we offer REST endpoints only. Widgets use polling (every 60 seconds) for live updates. We may add WebSocket support in the future based on demand.
Can I contribute or report bugs?
Yes! If you find a bug or have a feature request, please reach out via our contact page. We love community feedback.
Do I need to attribute ServerHub?
Attribution is appreciated but not strictly required for the Status API. For badges and widgets, the default embed code includes a ServerHub link which we ask you to keep as a courtesy.

Ready to Build?

Start using the API right now — no sign-up required.

Try Status CheckerAll Tools