Getting Started

Learn how to integrate HytList voting system with your server.

Overview

The HytList API allows you to verify if players have voted for your server in the last 24 hours. Use this to reward voters with in-game items, ranks, or other benefits.

REST

API Type

JSON

Response Format

HTTPS

Protocol

Base URL

https://hytlist.org/api

Authentication

No Authentication Required

The API is publicly accessible. Make HTTP requests directly without API keys.

GET

Check Vote

Verify if a player has voted for your server in the last 24 hours.

Endpoint

GET /api/vote/check/{server}/{username}

Parameters

Parameter	Type	Description
`server`	string	Your server slug (from URL: hytlist.org/server/your-slug)
`username`	string	Player's in-game username

Example Request

curl "https://hytlist.org/api/vote/check/my-server/Steve"

Response Format

Understanding API responses and data structures.

Player Has Voted

{
    "server": "my-server",
    "username": "Steve",
    "has_voted": true,
    "voted_at": "2026-01-15T12:34:56.000000Z"
}

Player Has Not Voted

{
    "server": "my-server",
    "username": "Steve",
    "has_voted": false,
    "voted_at": null
}

Response Fields

Field	Type	Description
`has_voted`	boolean	True if voted within last 24 hours
`voted_at`	string\|null	ISO 8601 timestamp or null
`server`	string	Server slug queried
`username`	string	Username queried

Error Handling

HTTP status codes and error responses.

Status Codes

Code	Status	Description
200	OK	Request successful
404	Not Found	Server slug not found
429	Too Many Requests	Rate limit exceeded (60/min)
500	Server Error	Internal server error

Error Response

{
    "error": "Server not found",
    "message": "No server exists with slug 'invalid-server'"
}

Rate Limits

60

requests/min

24h

vote validity

5s

cache time

Code Examples

Ready-to-use code snippets for popular languages.

Java (Bukkit/Spigot)

import java.net.*;
import java.io.*;
import com.google.gson.*;

public class VoteChecker {
    private static final String API = "https://hytlist.org/api/vote/check/";
    private final String serverSlug;

    public VoteChecker(String serverSlug) {
        this.serverSlug = serverSlug;
    }

    public boolean hasVoted(String username) {
        try {
            URL url = new URL(API + serverSlug + "/" + username);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("GET");
            conn.setConnectTimeout(5000);
            conn.setReadTimeout(5000);

            if (conn.getResponseCode() != 200) return false;

            BufferedReader reader = new BufferedReader(
                new InputStreamReader(conn.getInputStream())
            );
            JsonObject json = JsonParser.parseReader(reader).getAsJsonObject();
            reader.close();

            return json.get("has_voted").getAsBoolean();
        } catch (Exception e) {
            e.printStackTrace();
            return false;
        }
    }
}

// Usage
VoteChecker checker = new VoteChecker("your-server-slug");
if (checker.hasVoted(player.getName())) {
    player.sendMessage("Thanks for voting!");
}

Lua (Hytale Modding)

local API_URL = "https://hytlist.org/api/vote/check/"
local SERVER_SLUG = "your-server-slug"

local function checkVote(username, callback)
    local url = API_URL .. SERVER_SLUG .. "/" .. username

    http.get(url, function(response)
        if response.success then
            local data = json.decode(response.body)
            callback(data.has_voted)
        else
            callback(false)
        end
    end)
end

-- Usage
checkVote(player:getName(), function(hasVoted)
    if hasVoted then
        player:sendMessage("Thanks for voting!")
    end
end)

Python

import requests

def check_vote(server_slug: str, username: str) -> bool:
    url = f"https://hytlist.org/api/vote/check/{server_slug}/{username}"

    try:
        response = requests.get(url, timeout=5)
        response.raise_for_status()
        return response.json().get("has_voted", False)
    except requests.RequestException:
        return False

# Usage
if check_vote("your-server-slug", "PlayerName"):
    print("Player has voted!")

JavaScript / Node.js

async function checkVote(serverSlug, username) {
    const url = `https://hytlist.org/api/vote/check/${serverSlug}/${username}`;

    try {
        const response = await fetch(url);
        const data = await response.json();
        return data.has_voted;
    } catch (error) {
        console.error('Vote check failed:', error);
        return false;
    }
}

// Usage
const hasVoted = await checkVote('your-server-slug', 'PlayerName');
if (hasVoted) {
    console.log('Player has voted!');
}

Best Practices

Cache results — Store vote status for at least 5 seconds
Check on join — Verify votes when players connect
Use timeouts — Set 5-10 second timeouts on requests
Async requests — Don't block game threads