API Documentation

Submit votes and server status to HyServers.gg programmatically from your game server or website.

Authentication

All API requests require a server API token. Generate one from your server dashboard under the API Access section.

Include the token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Keep your API token secret. Do not expose it in client-side code or public repositories.

Base URL

https://hyservers.gg/api/v1

Submit Vote

POST

/api/v1/servers/{server_id}/vote

Submit a vote for a server on behalf of a player.

Request Body

JSON

{
  "username": "PlayerName"
}

Parameters

username

requiredstring, 1-50 characters

The in-game username of the player voting.

Success Response (200)

JSON

{
  "success": true,
  "monthly_votes": 42,
  "next_vote_at": "2025-01-16T12:00:00.000Z"
}

Cooldown Response (429)

JSON

{
  "error": "This username has already voted for this server in the last 24 hours",
  "next_vote_at": "2025-01-16T12:00:00.000Z"
}

Cooldown: Each username can vote once per 24 hours per server. If your server has Votifier configured, votes will be automatically forwarded to your game server.

Submit Server Status

POST

/api/v1/servers/{server_id}/status

Submit your server's current status and player count. This data will appear in the server stats chart.

Request Body

JSON

{
  "online_players": 24,
  "max_players": 100,
  "latency_ms": 45,
  "motd": "Welcome to my server!",
  "server_version": "1.0.0"
}

Parameters

online_players

requirednumber

Current number of online players.

max_players

requirednumber

Maximum player capacity.

latency_ms

optional, number

Server latency in milliseconds.

motd

optional, string

Message of the day (max 500 chars).

server_version

optional, string

Server version string (max 100 chars).

Success Response (200)

JSON

{
  "success": true
}

Rate Limit Response (429)

JSON

{
  "error": "Rate limited. You can submit status once every 5 minutes.",
  "next_allowed_at": "2025-01-16T12:05:00.000Z"
}

Query Server Info

GET

/api/v1/servers/{server_id}/info

Retrieve your server's current status, player counts, averages, vote stats, rank, and more.

Response Fields

nameServer name

statusonline, offline, or unknown

online_playersCurrent player count

max_playersMaximum player capacity

average_players7-day average player count

peak_players7-day peak player count

latency_msCurrent latency in ms

average_latency30-day average latency

uptime_percentage30-day uptime percentage

monthly_votesCurrent month vote count

all_time_votesTotal votes since listing

rank_positionCurrent ranking position

Also includes: slug, address, connection_port, country_code, motd, server_version, votes_count, is_premium, last_checked_at, date_added

Example Response (200)

JSON

{
  "name": "My Hytale Server",
  "slug": "my-hytale-server",
  "address": "play.example.com",
  "connection_port": 25565,
  "country_code": "US",
  "status": "online",
  "online_players": 24,
  "max_players": 100,
  "average_players": 18.5,
  "peak_players": 87,
  "latency_ms": 45,
  "average_latency": 52.3,
  "uptime_percentage": 98.7,
  "motd": "Welcome to my server!",
  "server_version": "1.0.0",
  "votes_count": 150,
  "monthly_votes": 42,
  "all_time_votes": 1200,
  "rank_position": 5,
  "is_premium": false,
  "last_checked_at": "2026-02-06T12:00:00.000Z",
  "date_added": "2025-11-01T00:00:00.000Z"
}

No rate limit. This is a read-only endpoint. Average and peak stats are computed daily from status history.

Fetch Reviews

GET

/api/v1/servers/{server_id}/reviews

Fetch your server's reviews with rating summary and pagination.

Query Parameters

page

optional, number (default: 1)

Page number for pagination.

limit

optional, number (default: 10, max: 50)

Number of reviews per page.

Response Fields

review_countTotal number of reviews

average_ratingAverage rating out of 5

Each review includes: username, rating (1-5), content, created_at

Example Response (200)

JSON

{
  "review_count": 15,
  "average_rating": 4.2,
  "reviews": [
    {
      "username": "Player1",
      "rating": 5,
      "content": "Great server with an amazing community!",
      "created_at": "2026-02-05T14:30:00.000Z"
    },
    {
      "username": "Player2",
      "rating": 4,
      "content": "Good gameplay, could use more maps.",
      "created_at": "2026-02-04T09:15:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 15,
    "total_pages": 2
  }
}

No rate limit. This is a read-only endpoint. Only approved reviews are returned.

Error Responses

401

Missing or invalid API token.

400

Invalid request body (missing required fields, invalid values).

429

Rate limited. Votes: 1 per username per 24h. Status: 1 per 5 minutes.

500

Internal server error. Try again later.

Code Examples

Submit a Vote (JavaScript / Node.js)

JavaScript

const SERVER_ID = "your-server-id";
const API_TOKEN = "hys_your_api_token";

async function submitVote(username) {
  const response = await fetch(
    `https://hyservers.gg/api/v1/servers/${SERVER_ID}/vote`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${API_TOKEN}`,
      },
      body: JSON.stringify({ username }),
    }
  );

  const data = await response.json();

  if (response.ok) {
    console.log(`Vote recorded! Monthly votes: ${data.monthly_votes}`);
  } else if (response.status === 429) {
    console.log(`On cooldown until: ${data.next_vote_at}`);
  } else {
    console.error(`Error: ${data.error}`);
  }

  return data;
}

Submit Server Status (JavaScript / Node.js)

JavaScript

const SERVER_ID = "your-server-id";
const API_TOKEN = "hys_your_api_token";

async function submitStatus(onlinePlayers, maxPlayers) {
  const response = await fetch(
    `https://hyservers.gg/api/v1/servers/${SERVER_ID}/status`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${API_TOKEN}`,
      },
      body: JSON.stringify({
        online_players: onlinePlayers,
        max_players: maxPlayers,
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    console.error(`Error: ${data.error}`);
  }

  return data;
}

// Example: submit every 5 minutes
setInterval(() => {
  submitStatus(getOnlinePlayers(), getMaxPlayers());
}, 5 * 60 * 1000);

Query Server Info (JavaScript / Node.js)

JavaScript

const SERVER_ID = "your-server-id";
const API_TOKEN = "hys_your_api_token";

async function getServerInfo() {
  const response = await fetch(
    `https://hyservers.gg/api/v1/servers/${SERVER_ID}/info`,
    {
      headers: {
        "Authorization": `Bearer ${API_TOKEN}`,
      },
    }
  );

  const data = await response.json();

  if (response.ok) {
    console.log(`${data.name}: ${data.online_players}/${data.max_players} players`);
    console.log(`Rank #${data.rank_position} | ${data.monthly_votes} votes this month`);
    console.log(`Uptime: ${data.uptime_percentage}% | Avg players: ${data.average_players}`);
  } else {
    console.error(`Error: ${data.error}`);
  }

  return data;
}

Fetch Reviews (JavaScript / Node.js)

JavaScript

const SERVER_ID = "your-server-id";
const API_TOKEN = "hys_your_api_token";

async function getReviews(page = 1, limit = 10) {
  const response = await fetch(
    `https://hyservers.gg/api/v1/servers/${SERVER_ID}/reviews?page=${page}&limit=${limit}`,
    {
      headers: {
        "Authorization": `Bearer ${API_TOKEN}`,
      },
    }
  );

  const data = await response.json();

  if (response.ok) {
    console.log(`${data.review_count} reviews | Rating: ${data.average_rating}/5`);
    data.reviews.forEach(r =>
      console.log(`  ${r.username}: ${r.rating}/5 - ${r.content || "(no comment)"}`)
    );
  } else {
    console.error(`Error: ${data.error}`);
  }

  return data;
}

Using cURL

bash

# Submit a vote
curl -X POST https://hyservers.gg/api/v1/servers/YOUR_SERVER_ID/vote \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{"username": "PlayerName"}'

# Submit server status
curl -X POST https://hyservers.gg/api/v1/servers/YOUR_SERVER_ID/status \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{"online_players": 24, "max_players": 100}'

# Query server info
curl https://hyservers.gg/api/v1/servers/YOUR_SERVER_ID/info \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Fetch reviews
curl "https://hyservers.gg/api/v1/servers/YOUR_SERVER_ID/reviews?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Rate Limits

Endpoint	Limit	Scope
/vote	1 per 24 hours	Per username per server
/status	1 per 5 minutes	Per server
/info	No limit	Read-only
/reviews	No limit	Read-only