Submit

API Documentation

Integrate vote checking, server info, and vote webhooks into your game server.

Looking for a ready-made plugin?

View step-by-step integration guides for Minecraft, Rust, FiveM, WoW, and more.

Getting Started

  1. Log in and go to My Servers
  2. Click the API button on an approved server
  3. Click Generate API Key — copy and store the key securely
  4. Use the key in the Authorization header of your requests

Authentication

All v1 endpoints require a Bearer token. Include your API key in the Authorization header: 

Authorization: Bearer tgs_your_api_key_here

Each API key is bound to a single server. The endpoints automatically return data for the key's server.

Rate Limits

Endpoint Limit
GET /api/v1/server 60 requests / minute
GET /api/v1/votes 60 requests / minute
GET /api/v1/vote-check 120 requests / minute

When rate limited, you'll receive a 429 response with a Retry-After header (seconds).

Endpoints

GET /api/v1/server

Returns info about the server associated with your API key.

Response:

{
  "id": "uuid",
  "name": "My Server",
  "slug": "my-server",
  "game_id": "uuid",
  "status": "approved",
  "ip": "play.example.com",
  "port": 25565,
  "players_online": 42,
  "players_max": 100,
  "votes_total": 1234,
  "votes_weekly": 56,
  "votes_monthly": 200
}
GET /api/v1/votes

Returns vote counts. Optionally check if a specific user voted today.

Query parameters:

username Optional. Check if this user voted today.

Response:

{
  "total": 1234,
  "weekly": 56,
  "monthly": 200,
  "hasVoted": true   // only if ?username is provided
}
GET /api/v1/vote-check

Quick check if a player voted today. Designed for game server vote-reward plugins.

Query parameters:

username Required. The player's topgservers username.

Response:

{
  "voted": true,
  "last_vote_at": "2026-05-11T14:30:00.000Z"
}

Vote Webhook

Configure a webhook URL in your API key settings to receive real-time notifications when someone votes for your server.

Payload (POST):

{
  "event": "vote",
  "server_id": "uuid",
  "user_id": "uuid",
  "username": "PlayerName",
  "voted_at": "2026-05-11T14:30:00.000Z"
}

Signature verification:

Each webhook includes an X-TopG-Signature header for verification: 

X-TopG-Signature: t=1715443800,v1=a1b2c3d4e5f6...

The signature is an HMAC-SHA256 of {timestamp}.{json_body} using your webhook secret.

Verification example (Node.js):

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const parts = signature.split(',');
  const timestamp = parts.find(p => p.startsWith('t=')).slice(2);
  const receivedHmac = parts.find(p => p.startsWith('v1=')).slice(3);

  const expected = crypto
    .createHmac('sha256', secret)
    .update(timestamp + '.' + body)
    .digest('hex');

  // Timing-safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(receivedHmac)
  );
}

Examples

cURL

# Check if a player voted today
curl -H "Authorization: Bearer tgs_your_key" \
  "https://topgservers.net/api/v1/vote-check?username=PlayerName"

# Get server info
curl -H "Authorization: Bearer tgs_your_key" \
  "https://topgservers.net/api/v1/server"

# Get vote counts
curl -H "Authorization: Bearer tgs_your_key" \
  "https://topgservers.net/api/v1/votes"

JavaScript / Node.js

const API_KEY = 'tgs_your_key';
const BASE = 'https://topgservers.net/api/v1';

async function hasPlayerVoted(username) {
  const res = await fetch(
    BASE + '/vote-check?username=' + encodeURIComponent(username),
    { headers: { Authorization: 'Bearer ' + API_KEY } }
  );
  const data = await res.json();
  return data.voted;
}

Java (Minecraft Plugin)

import java.net.http.*;
import java.net.URI;

public class TopGVoteChecker {
    private static final String API_KEY = "tgs_your_key";
    private static final String BASE = "https://topgservers.net/api/v1";
    private final HttpClient client = HttpClient.newHttpClient();

    public boolean hasVoted(String username) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(BASE + "/vote-check?username=" + username))
            .header("Authorization", "Bearer " + API_KEY)
            .GET()
            .build();

        HttpResponse<String> response =
            client.send(request, HttpResponse.BodyHandlers.ofString());

        // Parse JSON (use Gson or similar in production)
        return response.body().contains("\"voted\":true");
    }
}