SortMC API Documentation

Welcome to the SortMC API documentation. Our APIs allow server owners and developers to integrate with our platform programmatically.

Server Owner API

Access your server's data programmatically using your unique API key.

Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Get Server Data

GET /api/server-owner

Returns comprehensive data about your server including real-time statistics.

Response Example:

{
  "server": {
    "id": "uuid",
    "server_name": "My Awesome Server",
    "server_address": "play.example.com",
    "country_code": "US",
    "country_override_code": null,
    "language": "en",
    "short_description": "The best Minecraft server ever!",
    "long_description": "Detailed description...",
    "icon_url": "https://...",
    "banner_url": "https://...",
    "banner_extension": "png",
    "supports_multiple_versions": false,
    "single_version": "1.20.1",
    "min_version": null,
    "max_version": null,
    "game_modes": ["survival", "creative"],
    "votifier_enabled": true,
    "votifier_ip": "123.45.67.89",
    "votifier_port": 8192,
    "created_at": "2024-01-01T00:00:00.000Z",
    "updated_at": "2024-01-15T00:00:00.000Z",
    "slug": "my-awesome-server",
    "unlisted": false,
    "vote_count_24h": 42,
    "status": {
      "is_online": true,
      "players_online": 15,
      "max_players": 100,
      "last_checked": "2024-01-15T00:05:00.000Z"
    }
  }
}

Error Responses

401 Unauthorized - Missing or invalid API key
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server error

Getting Your API Key

API keys are generated automatically when you create a server.

Go to your server's edit page and use API Key Management to view your current API key or generate a new one. Keep your API key secure and don't share it publicly.

Rate Limits

• Server Owner API: 100 requests per hour per API key

• Rate limit headers are included in all responses:

  • X-RateLimit-Limit: Maximum requests allowed
  • X-RateLimit-Remaining: Requests remaining in current window
  • X-RateLimit-Reset: Unix timestamp when limit resets

• Server creation is limited to 3 servers per user

429 Too Many Requests will be returned when rate limit is exceeded, with a Retry-After header indicating when to retry.

Public Banner API

Generate embeddable server banners for websites, forums, and Discord profiles.

Endpoint

GET /api/banners/:slug

Returns a live SVG image with server IP address(es), votes (24h), player count, and rating (90d).

Query Parameters

  • theme: dark | light | emerald (default: dark)
  • style: card | compact (default: card)

Example

<a href="https://sortmc.com/my-server-slug" target="_blank" rel="noopener noreferrer">
  <img
    src="https://sortmc.com/api/banners/my-server-slug?theme=dark&style=card"
    alt="My Server on SortMC"
  />
</a>

Private listings never expose hidden IP addresses in public banners.

Support

If you need help with the API or have questions:

  • • Check our Server Rules for API usage guidelines
  • • Contact us through our support channels
  • • Report API issues or request features

Code Examples

JavaScript/Node.js

const response = await fetch('https://sortmc.com/api/server-owner', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log('Server data:', data.server);

Python

import requests

headers = {'Authorization': 'Bearer YOUR_API_KEY'}
response = requests.get('https://sortmc.com/api/server-owner', headers=headers)
data = response.json()

print('Server name:', data['server']['server_name'])
print('Players online:', data['server']['status']['players_online'])
print('Votes (24h):', data['server']['vote_count_24h'])

cURL

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://sortmc.com/api/server-owner