DEV Community

Draginox
Draginox

Posted on

Free Minecraft Server Status API: Build Dashboards, Bots, and Widgets

#api #javascript #tutorial #webdev

If you run a Minecraft server or build tools for the Minecraft community, you've probably needed real-time server status data: is the server online? How many players are connected? What version is it running?

I built a free API that answers these questions for any Minecraft server — and it powers Minecraft ServerHub, which monitors 5000+ servers. Here's how to use it.

The Badge API: Instant Status Widgets

The simplest way to show your server's status is an embeddable SVG badge. No API key needed, no JavaScript required:

<img src="https://minecraft-serverhub.com/api/badge/play.hypixel.net" alt="Server Status" />
Enter fullscreen mode Exit fullscreen mode

This renders a live badge showing online/offline status and player count. It updates automatically — just drop the <img> tag on your website.

Customization Options

Parameter Values Default
style rounded, flat, minecraft rounded
label Any text Server IP
players true, false true
version true, false false
dark true, false false

Examples:

# Flat style with custom label
/api/badge/play.example.com?style=flat&label=My%20Server

# Dark mode with version info
/api/badge/play.example.com?dark=true&version=true

# Minimal — just online/offline
/api/badge/play.example.com?players=false
Enter fullscreen mode Exit fullscreen mode

You can generate badges interactively with the badge generator tool — it gives you copy-paste HTML, Markdown, and BBCode.

Embedding on Different Platforms

HTML (websites):

<a href="https://minecraft-serverhub.com/servers?q=play.example.com">
  <img src="https://minecraft-serverhub.com/api/badge/play.example.com"
       alt="Server Status" />
</a>
Enter fullscreen mode Exit fullscreen mode

Markdown (GitHub README, Discord):

[![Server Status](https://minecraft-serverhub.com/api/badge/play.example.com)](https://minecraft-serverhub.com)
Enter fullscreen mode Exit fullscreen mode

BBCode (Minecraft forums, SpigotMC):

[url=https://minecraft-serverhub.com][img]https://minecraft-serverhub.com/api/badge/play.example.com[/img][/url]
Enter fullscreen mode Exit fullscreen mode

How the Badge API Works Internally

The badge endpoint generates an SVG on the fly. Here's the simplified flow:

export async function GET(request: NextRequest, { params }) {
  const { address } = await params;
  const style = url.searchParams.get("style") || "rounded";

  // Look up server in database
  const server = await prisma.server.findFirst({
    where: {
      OR: [
        { ipAddress: address },
        { slug: address },
      ],
      status: { in: ["ACTIVE", "PENDING"] },
    },
    select: {
      name: true,
      isOnline: true,
      playersOnline: true,
      maxPlayers: true,
      version: true,
    },
  });

  // Generate dynamic SVG
  const svg = generateBadgeSVG({ server, style, address });

  return new NextResponse(svg, {
    headers: {
      "Content-Type": "image/svg+xml",
      "Cache-Control": "public, s-maxage=120, stale-while-revalidate=300",
      "Access-Control-Allow-Origin": "*",
    },
  });
}
Enter fullscreen mode Exit fullscreen mode

Key design decisions:

  1. SVG, not PNG — SVG is vector-based, looks crisp at any size, and is tiny (~1KB vs 5KB+ for PNG).
  2. CORS wildcard — Access-Control-Allow-Origin: * lets anyone embed it.
  3. 2-minute cache — s-maxage=120 with stale-while-revalidate=300 keeps CDN load low while data stays reasonably fresh.

The SVG generation uses shields.io-style badges. The left side shows the server name/IP, and the right side shows the status with a green (online) or red (offline) background.

Building a Discord Bot with the API

Here's a quick Discord bot that checks server status on command:

const { Client, GatewayIntentBits, EmbedBuilder } = require("discord.js");

const client = new Client({
  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages],
});

client.on("interactionCreate", async (interaction) => {
  if (!interaction.isChatInputCommand()) return;

  if (interaction.commandName === "status") {
    const address = interaction.options.getString("server");

    // Fetch from the API
    const res = await fetch(
      `https://minecraft-serverhub.com/api/servers/search?q=${encodeURIComponent(address)}`
    );
    const data = await res.json();
    const server = data.servers?.[0];

    if (!server) {
      return interaction.reply("Server not found in our database.");
    }

    const embed = new EmbedBuilder()
      .setTitle(server.name)
      .setColor(server.isOnline ? 0x22c55e : 0xef4444)
      .addFields(
        { name: "Status", value: server.isOnline ? "Online" : "Offline", inline: true },
        { name: "Players", value: `${server.playersOnline}/${server.maxPlayers}`, inline: true },
        { name: "Version", value: server.version || "Unknown", inline: true }
      )
      .setFooter({ text: "Data from minecraft-serverhub.com" });

    return interaction.reply({ embeds: [embed] });
  }
});
Enter fullscreen mode Exit fullscreen mode

Building a Server Status Page

Many server owners want a status page on their own website. Here's a React component:

import { useState, useEffect } from "react";

function ServerStatus({ address }: { address: string }) {
  const [server, setServer] = useState(null);

  useEffect(() => {
    const fetchStatus = async () => {
      const res = await fetch(
        `https://minecraft-serverhub.com/api/servers/search?q=${address}`
      );
      const data = await res.json();
      setServer(data.servers?.[0] ?? null);
    };

    fetchStatus();
    const interval = setInterval(fetchStatus, 60000); // Refresh every minute
    return () => clearInterval(interval);
  }, [address]);

  if (!server) return <div>Loading...</div>;

  return (
    <div style={{
      display: "flex",
      alignItems: "center",
      gap: "8px",
      padding: "12px",
      borderRadius: "8px",
      background: server.isOnline ? "#f0fdf4" : "#fef2f2",
    }}>
      <div style={{
        width: 12,
        height: 12,
        borderRadius: "50%",
        background: server.isOnline ? "#22c55e" : "#ef4444",
      }} />
      <span>{server.name}</span>
      <span style={{ marginLeft: "auto", fontWeight: "bold" }}>
        {server.playersOnline}/{server.maxPlayers} players
      </span>
    </div>
  );
}
Enter fullscreen mode Exit fullscreen mode

Or even simpler — just use the badge:

<!-- Zero JavaScript, auto-updates -->
<img src="https://minecraft-serverhub.com/api/badge/play.example.com?style=flat"
     alt="Server Status"
     style="height: 20px;" />
Enter fullscreen mode Exit fullscreen mode

Rate Limits and Fair Use

The API is free with reasonable limits:

  • Badge API: No hard limit, CDN cached for 2 minutes
  • Search API: Rate limited per IP (reasonable use)
  • No API key required for read-only badge endpoints

If you need higher limits or want server data in bulk, check the ServerHub statistics page for aggregate data.

Use Cases I've Seen

Since launching the API, people have built:

  • Discord bots that post hourly server status updates
  • Forum signatures with live player counts
  • Twitch stream overlays showing the server they're playing on
  • Server websites with embedded status badges
  • Monitoring dashboards tracking multiple servers

The badge alone gets embedded on hundreds of server websites, which is great for the Minecraft community — everyone can see at a glance if a server is up.

Getting Started

  1. Quick badge: Replace play.example.com with your server IP: 
   https://minecraft-serverhub.com/api/badge/play.example.com
Enter fullscreen mode Exit fullscreen mode

  1. Customize it: Use the interactive badge generator

  2. Build with it: Hit the search API for structured data:

   https://minecraft-serverhub.com/api/servers/search?q=play.example.com
Enter fullscreen mode Exit fullscreen mode
  1. Track your server: Add it to ServerHub for free monitoring, voting, and analytics.

The entire platform is free. No sign-up needed for badges, no API key for basic status checks. If you run a Minecraft server, there's no reason not to have a live status badge on your website.

Questions? Found a bug? Open an issue or reach out. And if you build something cool with the API, I'd love to see it.

Top comments (0)