API v1

Developer API

Access server data programmatically. Build integrations, bots, and applications with our REST API.

Access our complete Hytale server list programmatically with live player counts, status, and rankings.

Quick Start

Create an API key from your dashboard
Include the key in your requests via the Authorization header
Make requests to https://hytaletopservers.net/api/v1/

Example request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://hytaletopservers.net/api/v1/servers

Authentication

All API requests require an API key. Include your key in the Authorizationheader:

Authorization: Bearer hts_xxxxxxxxxxxx

Important: Keep your API key secret. Never expose it in client-side code or public repositories.

Rate Limiting

API requests are rate limited to ensure fair usage:

1,000 requests per day per API key
Rate limits reset at midnight UTC
Exceeding limits returns 429 Too Many Requests

Rate limit information is included in every response:

{
  "meta": {
    "rateLimit": {
      "limit": 1000,
      "remaining": 999,
      "reset": "2024-01-01T00:00:00Z"
    }
  }
}

Endpoints

GET/api/v1/servers

List servers with pagination and filtering

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Results per page (1-100, default: 20)
`sort`	string	votesMonth, votesAllTime, players, newest, oldest
`tag`	string	Filter by tag (e.g., PVP, SURVIVAL)
`country`	string	Filter by country code (e.g., US, GB)
`search`	string	Search by name or description
`online`	boolean	Filter to online servers only

Response

{
  "success": true,
  "data": {
    "servers": [
      {
        "id": "abc123",
        "name": "Example Server",
        "address": "play.example.com",
        "port": 5520,
        "description": "A great Hytale server",
        "tags": ["PVP", "SURVIVAL"],
        "country": "US",
        "icon": "https://hytaletopservers.net/uploads/icons/...",
        "status": {
          "online": true,
          "players": 42,
          "maxPlayers": 100,
          "version": "1.0.0"
        },
        "votes": {
          "month": 150,
          "allTime": 1200
        },
        "createdAt": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 100,
      "totalPages": 5,
      "hasMore": true
    }
  },
  "meta": {
    "rateLimit": { ... }
  }
}

GET/api/v1/servers/:id

Get detailed information about a specific server

Response

{
  "success": true,
  "data": {
    "id": "abc123",
    "name": "Example Server",
    "address": "play.example.com",
    "port": 5520,
    "description": {
      "short": "A great Hytale server",
      "full": "Full description with markdown..."
    },
    "tags": ["PVP", "SURVIVAL"],
    "country": "US",
    "images": {
      "icon": "https://...",
      "banner": "https://..."
    },
    "links": {
      "website": "https://example.com",
      "discord": "https://discord.gg/..."
    },
    "status": {
      "online": true,
      "players": 42,
      "maxPlayers": 100,
      "version": "1.0.0",
      "lastChecked": "2024-01-01T00:00:00Z"
    },
    "votes": {
      "month": 150,
      "allTime": 1200
    },
    "createdAt": "2024-01-01T00:00:00Z"
  }
}

GET/api/v1/servers/:id/status

Get real-time server status (requires status permission)

Response

{
  "success": true,
  "data": {
    "id": "abc123",
    "name": "Example Server",
    "address": "play.example.com",
    "port": 5520,
    "online": true,
    "players": 42,
    "maxPlayers": 100,
    "version": "1.0.0",
    "motd": "Welcome to our server!",
    "queriedAt": "2024-01-01T00:00:00Z"
  }
}

Error Handling

All errors return a consistent format:

{
  "success": false,
  "error": "Error message here"
}

Common Error Codes

Code	Description
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Missing or invalid API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn't exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

Code Examples

JavaScript / TypeScript

const API_KEY = 'hts_xxxxxxxxxxxx';
const BASE_URL = 'https://hytaletopservers.net/api/v1';

async function getServers(options = {}) {
  const params = new URLSearchParams(options);
  const response = await fetch(`${BASE_URL}/servers?${params}`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
    },
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return response.json();
}

// Usage
const result = await getServers({ tag: 'PVP', limit: 10 });
console.log(result.data.servers);

Python

import requests

API_KEY = 'hts_xxxxxxxxxxxx'
BASE_URL = 'https://hytaletopservers.net/api/v1'

def get_servers(**kwargs):
    response = requests.get(
        f'{BASE_URL}/servers',
        params=kwargs,
        headers={'Authorization': f'Bearer {API_KEY}'}
    )
    response.raise_for_status()
    return response.json()

# Usage
result = get_servers(tag='PVP', limit=10)
print(result['data']['servers'])

cURL

# List servers
curl -H "Authorization: Bearer hts_xxxxxxxxxxxx" \
  "https://hytaletopservers.net/api/v1/servers?tag=PVP&limit=10"

# Get specific server
curl -H "Authorization: Bearer hts_xxxxxxxxxxxx" \
  "https://hytaletopservers.net/api/v1/servers/abc123"

# Get real-time status
curl -H "Authorization: Bearer hts_xxxxxxxxxxxx" \
  "https://hytaletopservers.net/api/v1/servers/abc123/status"

Ready to Get Started?

Create your API key and start building integrations today.

Get Your API Key