API Documentation

Integrate Minecraft server status checking into your applications with our public API.

Quick Start

Our API allows you to fetch real-time status information for any Minecraft server. No API key required for basic usage, but rate limits apply.

Base URL

http://localhost:3000/api/server

Endpoints

GET/api/server

Fetch the status of a Minecraft server (Java Edition or Bedrock Edition).

Query Parameters

hostrequired

The server hostname or IP address (e.g., "mc.hypixel.net")

portoptional

The server port (default: 25565 for Java, 19132 for Bedrock)

typeoptional

Server type: "java" or "bedrock" (default: "java")

Example Request

GET /api/server?host=mc.hypixel.net&type=java

# With cURL
curl "http://localhost:3000/api/server?host=mc.hypixel.net&type=java"

# With JavaScript (fetch)
fetch('http://localhost:3000/api/server?host=mc.hypixel.net&type=java')
  .then(res => res.json())
  .then(data => console.log(data));

# With Python (requests)
import requests
response = requests.get(
    'http://localhost:3000/api/server',
    params={'host': 'mc.hypixel.net', 'type': 'java'}
)
data = response.json()

Success Response (200 OK)

{
  "online": true,
  "host": "mc.hypixel.net",
  "port": 25565,
  "players": {
    "online": 45123,
    "max": 200000
  },
  "version": "Requires MC 1.8 / 1.21",
  "motd": {
    "raw": "§aHypixel Network §c[1.8-1.21]",
    "clean": "Hypixel Network [1.8-1.21]",
    "html": "<span style='color:#55ff55'>Hypixel Network</span>..."
  },
  "favicon": "data:image/png;base64,iVBORw0KGgo...",
  "ping": 45,
  "lastUpdated": "2024-01-15T12:34:56.789Z"
}

Error Response (Offline Server)

{
  "online": false,
  "host": "offline.server.net",
  "port": 25565,
  "error": "Server is offline or unreachable"
}

Authentication

Turnstile Verification Required

To prevent abuse, all API requests must include a valid Cloudflare Turnstile token. This is automatically handled when using our website, but external API consumers must implement Turnstile verification.

Request Headers

Content-Type: application/json
X-Turnstile-Token: <your-turnstile-token>

Learn more about implementing Cloudflare Turnstile:Cloudflare Turnstile Docs

Rate Limits

To ensure fair usage and prevent abuse, the following rate limits are enforced:

Per Server

40 seconds

Minimum cooldown between requests for the same server

Per IP Address

60 req/hour

Maximum requests per IP address per hour

Rate Limit Response

When rate limited, you'll receive a 429 Too Many Requests response with a Retry-After header indicating when you can retry.

Example Rate Limit Response

HTTP/1.1 429 Too Many Requests
Retry-After: 35

{
  "error": "Rate limit exceeded. Please wait 35 seconds.",
  "retryAfter": 35
}

Response Fields

Field	Type	Description
`online`	boolean	Whether the server is online
`host`	string	Server hostname or IP
`port`	number	Server port
`players`	object	Player count (online/max)
`version`	string	Server version
`motd`	object	MOTD in various formats (raw/clean/html)
`favicon`	string	Base64 server icon (if available)
`ping`	number	Response time in milliseconds
`lastUpdated`	string	ISO 8601 timestamp
`error`	string	Error message (if offline)

Error Codes

Code	Status	Description
`400`	Bad Request	Missing or invalid parameters
`403`	Forbidden	Invalid or missing Turnstile token
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server error occurred
`503`	Service Unavailable	API temporarily unavailable

Best Practices

Cache responses for at least 40 seconds to respect rate limits
Handle errors gracefully with proper retry logic and exponential backoff
Implement Turnstile correctly to avoid authentication errors
Monitor rate limits and respect the Retry-After header
Use connection pooling for better performance
Set appropriate timeouts (recommended: 10-15 seconds)

Need Help?

If you encounter any issues or have questions about the API, please:

Open an issue on our GitHub repository
Check the general documentation for more information
Review our Terms of Service and Privacy Policy