Add Server
API v1

Public API

Free access to Hytale server data. Read-only, no authentication required.

🔗
Base URL https://hytale.surf/api/v1
⚡
Rate Limit 60 requests / min
📦
Format JSON · CORS enabled

Endpoints

Get a paginated list of servers with search and sorting.

Parameters

Parameter Type Default Description
page integer 1 Page number
limit integer 20 Results per page (max 100)
q string — Search query (up to 100 chars)
tag string — Filter by tag (e.g. PVP, SURVIVAL)
sort string default Sort: default, players, votes

Example Request

curl 
curl "https://hytale.surf/api/v1/servers?page=1&limit=5&sort=players"

Example Response

JSON 
{
  "data": [
    {
      "id": "a1b2c3d4e5f6",
      "name": "My Hytale Server",
      "ip": "play.example.com",
      "shortDescription": "A great server!",
      "players": 42,
      "maxPlayers": 100,
      "online": true,
      "country": "US",
      "votes": 120,
      "tags": ["PVP", "SURVIVAL"],
      ...
    }
  ],
  "meta": {
    "page": 1,
    "limit": 5,
    "total": 1129,
    "totalPages": 226
  }
}

Errors

HTTP Code Description
400 Invalid request parameters
404 Server not found
429 Rate limit exceeded (60/min)
500 Internal server error

Notes

  • The API is read-only. Modifying data via the API is not supported.
  • No authentication is required.
  • CORS is enabled for all origins — you can use it directly from the browser.
  • Responses are cached for 15–60 seconds for optimal performance.
  • Sensitive data (owner IDs) is stripped from all responses.