API Documentation

The GameServerList API allows you to integrate voting rewards and server information into your game server. All API endpoints return JSON responses.

Base URL

https://gameserverlist.net/api/v1

Rate Limits

• Free accounts: 60 requests per minute
• Premium accounts: 300 requests per minute

Some endpoints require authentication via an API key. You can find your API key in your server's settings in the dashboard.

Using Your API Key

Include your API key in the request header:

Authorization: Bearer YOUR_API_KEY

Or as a query parameter:

?api_key=YOUR_API_KEY

Check if a User Has Voted

Use this endpoint to check if a player has voted for your server and is eligible for rewards.

Query Parameters

Parameter	Type	Required	Description
steam_id	string	Yes*	Player's Steam ID (64-bit)
username	string	Yes*	Player's username on your server
ip	string	No	Player's IP address

*At least one identifier is required

Example Request

GET /api/v1/vote/check/12345?steam_id=76561198012345678&api_key=YOUR_KEY

Success Response

{
    "voted": true,
    "claimed": false,
    "vote_time": "2024-01-15T12:30:00Z",
    "next_vote": "2024-01-16T00:30:00Z"
}

Not Voted Response

{
    "voted": false,
    "vote_url": "https://gameserverlist.net/server/12345/vote"
}

Configure a callback URL in your server settings to receive real-time notifications when players vote.

Callback Request

We will send a POST request to your callback URL with the following data:

{
    "event": "vote",
    "server_id": 12345,
    "server_key": "your_server_key",
    "voter": {
        "steam_id": "76561198012345678",
        "username": "PlayerName",
        "ip": "123.45.67.89"
    },
    "timestamp": "2024-01-15T12:30:00Z",
    "signature": "sha256_signature_here"
}

Verifying the Signature

To ensure the callback is legitimate, verify the signature:

// PHP Example
$expected = hash_hmac('sha256', $server_id . $timestamp, $your_api_key);
if (hash_equals($expected, $received_signature)) {
    // Valid callback
}

Response Requirements

Your callback URL should return:

• HTTP 200 status for success
• Any 4xx or 5xx status for failure (we'll retry)

We will retry failed callbacks up to 3 times with exponential backoff.

Get Server Stats

Response

{
    "id": 12345,
    "name": "My Awesome Server",
    "game": "minecraft",
    "ip": "play.example.com",
    "port": 25565,
    "is_online": true,
    "players": {
        "current": 45,
        "max": 100
    },
    "votes": {
        "monthly": 1234,
        "total": 56789
    },
    "rank": 5
}

Get Server Vote Leaderboard

Response

{
    "period": "monthly",
    "voters": [
        {"username": "Player1", "votes": 30},
        {"username": "Player2", "votes": 28},
        {"username": "Player3", "votes": 25}
    ]
}

All errors return a JSON response with an error message:

{
    "error": true,
    "message": "Invalid API key",
    "code": "INVALID_API_KEY"
}

Error Codes

HTTP Status	Code	Description
400	BAD_REQUEST	Missing or invalid parameters
401	UNAUTHORIZED	Invalid or missing API key
404	NOT_FOUND	Server or resource not found
429	RATE_LIMITED	Too many requests
500	SERVER_ERROR	Internal server error