API v1

API para Desarrolladores

Accede a datos de servidores programáticamente. Crea integraciones, bots y aplicaciones con nuestra API REST.

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

Inicio Rápido

Crea una clave API desde tu panel de control
Incluye la clave en tus solicitudes a través del encabezado Authorization
Realiza solicitudes a https://hytaletopservers.net/api/v1/

Solicitud de ejemplo:

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

Autenticación

Todas las solicitudes de API requieren una clave API. Incluye tu clave en el encabezado Authorization:

Authorization: Bearer hts_xxxxxxxxxxxx

Importante: Mantén tu clave API en secreto. Nunca la expongas en código del lado del cliente o repositorios públicos.

Límite de Velocidad

Las solicitudes de API tienen un límite de velocidad para asegurar un uso justo:

1,000 solicitudes por día por clave API
Los límites de velocidad se restablecen a medianoche UTC
Exceder los límites devuelve 429 Too Many Requests

La información del límite de velocidad está incluida en cada respuesta:

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

Endpoints

GET/api/v1/servers

Lista servidores con paginación y filtrado

Parámetros de Consulta

Parámetro	Tipo	Descripción
`page`	integer	Número de página (predeterminado: 1)
`limit`	integer	Resultados por página (1-100, predeterminado: 20)
`sort`	string	votesMonth, votesAllTime, players, newest, oldest
`tag`	string	Filtrar por etiqueta (ej: PVP, SURVIVAL)
`country`	string	Filtrar por código de país (ej: US, ES)
`search`	string	Buscar por nombre o descripción
`online`	boolean	Filtrar solo servidores en línea

Respuesta

{
  "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

Obtén información detallada sobre un servidor específico

Respuesta

{
  "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

Obtén el estado del servidor en tiempo real (requiere permiso status )

Respuesta

{
  "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"
  }
}

Manejo de Errores

Todos los errores devuelven un formato consistente:

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

Códigos de Error Comunes

Código	Descripción
`400`	Solicitud Incorrecta - Parámetros inválidos
`401`	No Autorizado - Clave API faltante o inválida
`403`	Prohibido - Permisos insuficientes
`404`	No Encontrado - El recurso no existe
`429`	Demasiadas Solicitudes - Límite de velocidad excedido
`500`	Error Interno del Servidor

Ejemplos de Código

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"

¿Listo para Comenzar?

Crea tu clave API y comienza a construir integraciones hoy.

Obtén Tu Clave API