MC
API Reference

API Documentation

Integrate MC Server List data into your applications, bots, or websites using our REST API.

Base URL

https://msl.appahouse.com/api

All API endpoints are relative to this base URL. Responses are in JSON format.

Authentication

Most read endpoints are public and don't require authentication. Write operations require authentication via session cookies or API keys.

Rate Limiting

API requests are rate limited to prevent abuse:

  • • Anonymous: 20 requests per minute
  • • Authenticated: 100 requests per minute

Endpoints

Servers

GET
/servers

List all approved servers with optional filtering and pagination.

Query Parameters

limit - Number of results (default: 20, max: 100)
offset - Pagination offset
sort - Sort by: votes, players, newest, uptime
type - Server type filter
gameMode - Game mode filter

Example Request

curl "https://msl.appahouse.com/api/servers?limit=10&sort=votes"

Example Response

{
  "servers": [
    {
      "id": "uuid-here",
      "name": "Example Server",
      "ipAddress": "play.example.com",
      "port": 25565,
      "isOnline": true,
      "currentPlayers": 42,
      "maxPlayers": 100,
      "voteCount": 1234,
      "serverType": "paper",
      "gameModes": ["survival", "skyblock"],
      ...
    }
  ],
  "total": 150,
  "hasMore": true
}
GET
/servers/:serverId

Get detailed information about a specific server.

Example Request

curl "https://msl.appahouse.com/api/servers/abc-123-uuid"
GET
/servers/:serverId/stats

Get historical statistics for a server (player counts, uptime, etc.).

Query Parameters

days - Number of days of history (default: 7, max: 30)

Voting

POST
/servers/:serverId/vote

Submit a vote for a server. Rate limited to one vote per IP per server per day.

Example Request

curl -X POST "https://msl.appahouse.com/api/servers/abc-123/vote"

Response

{
  "success": true,
  "newVoteCount": 1235,
  "nextVoteAt": "2024-01-16T00:00:00Z"
}

Real-time Updates

GET
/servers/status-stream

Server-Sent Events (SSE) endpoint for real-time server status updates.

Query Parameters

serverIds - Comma-separated server IDs to subscribe to (optional, defaults to all)

JavaScript Example

const eventSource = new EventSource('/api/servers/status-stream');

eventSource.onmessage = (event) => {
  const update = JSON.parse(event.data);
  console.log('Server status update:', update);
  // { type: 'status_update', serverId: '...', currentStatus: true, ... }
};

eventSource.onerror = (error) => {
  console.error('SSE error:', error);
};

Webhooks

Set up webhooks to receive real-time notifications when events happen on your server.

GET
/servers/:serverId/webhooks

List all webhooks configured for a server. Requires authentication.

POST
/servers/:serverId/webhooks

Create a new webhook. Supports Discord, Slack, and generic HTTP endpoints.

Request Body

{
  "name": "Discord Alerts",
  "url": "https://discord.com/api/webhooks/...",
  "webhookType": "discord",
  "events": ["server.vote", "server.offline", "server.milestone"]
}

Supported Events

server.vote - New vote received
server.review - New review posted
server.online - Server came online
server.offline - Server went offline
server.milestone - Vote milestone reached
POST
/servers/:serverId/webhooks/:webhookId/test

Send a test payload to verify your webhook is working correctly.

Error Handling

The API uses standard HTTP status codes and returns error details in JSON format.

200
Success
400
Bad Request - Invalid parameters
401
Unauthorized - Authentication required
403
Forbidden - Insufficient permissions
404
Not Found - Resource doesn't exist
429
Too Many Requests - Rate limited
500
Internal Server Error

Error Response Format

{
  "error": "Server not found",
  "code": "NOT_FOUND",
  "details": {}
}

Need More Help?

FAQ

Common questions answered

Server Owner Guide

Complete guide for server owners