API v1

API Développeur

Accédez aux données des serveurs par programmation. Créez des intégrations, des bots et des applications avec notre API REST.

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

Obtenir une Clé API

Démarrage Rapide

Créez une clé API depuis votre tableau de bord
Incluez la clé dans vos requêtes via l'en-tête Authorization
Effectuez des requêtes vers https://hytaletopservers.net/api/v1/

Exemple de requête :

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

Authentification

Toutes les requêtes API nécessitent une clé API. Incluez votre clé dans l'en-tête Authorization :

Authorization: Bearer hts_xxxxxxxxxxxx

Important : Gardez votre clé API secrète. Ne l'exposez jamais dans le code côté client ou les dépôts publics.

Limitation du Débit

Les requêtes API sont limitées en débit pour garantir une utilisation équitable :

1 000 requêtes par jour par clé API
Les limites de débit sont réinitialisées à minuit UTC
Le dépassement des limites renvoie 429 Too Many Requests

Les informations sur la limite de débit sont incluses dans chaque réponse :

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

Points de Terminaison

GET/api/v1/servers

Lister les serveurs avec pagination et filtrage

Paramètres de Requête

Paramètre	Type	Description
`page`	integer	Numéro de page (défaut : 1)
`limit`	integer	Résultats par page (1-100, défaut : 20)
`sort`	string	votesMonth, votesAllTime, players, newest, oldest
`tag`	string	Filtrer par tag (ex : PVP, SURVIVAL)
`country`	string	Filtrer par code pays (ex : US, FR)
`search`	string	Rechercher par nom ou description
`online`	boolean	Filtrer uniquement les serveurs en ligne

Réponse

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

Obtenir des informations détaillées sur un serveur spécifique

Réponse

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

Obtenir le statut du serveur en temps réel (nécessite la permission status )

Réponse

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

Gestion des Erreurs

Toutes les erreurs renvoient un format cohérent :

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

Codes d'Erreur Courants

Code	Description
`400`	Requête Incorrecte - Paramètres invalides
`401`	Non Autorisé - Clé API manquante ou invalide
`403`	Interdit - Permissions insuffisantes
`404`	Non Trouvé - La ressource n'existe pas
`429`	Trop de Requêtes - Limite de débit dépassée
`500`	Erreur Interne du Serveur

Exemples de Code

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"

Prêt à Commencer ?

Créez votre clé API et commencez à construire des intégrations dès aujourd'hui.

Obtenez Votre Clé API