API v1

Entwickler-API

Greife programmatisch auf Serverdaten zu. Erstelle Integrationen, Bots und Anwendungen mit unserer REST-API.

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

Schnellstart

Erstelle einen API-Schlüssel in deinem Dashboard
Füge den Schlüssel in deinen Anfragen über den Authorization -Header hinzu
Sende Anfragen an https://hytaletopservers.net/api/v1/

Beispielanfrage:

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

Authentifizierung

Alle API-Anfragen erfordern einen API-Schlüssel. Füge deinen Schlüssel in den Authorization-Header ein:

Authorization: Bearer hts_xxxxxxxxxxxx

Wichtig: Halte deinen API-Schlüssel geheim. Stelle ihn niemals in Client-seitigem Code oder öffentlichen Repositories bereit.

Ratenbegrenzung

API-Anfragen sind ratenbegrenzt, um faire Nutzung zu gewährleisten:

1.000 Anfragen pro Tag pro API-Schlüssel
Ratenbegrenzungen werden um Mitternacht UTC zurückgesetzt
Bei Überschreitung wird zurückgegeben 429 Too Many Requests

Ratenbegrenzungsinformationen sind in jeder Antwort enthalten:

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

Endpunkte

GET/api/v1/servers

Server mit Paginierung und Filterung auflisten

Abfrageparameter

Parameter	Typ	Beschreibung
`page`	integer	Seitennummer (Standard: 1)
`limit`	integer	Ergebnisse pro Seite (1-100, Standard: 20)
`sort`	string	votesMonth, votesAllTime, players, newest, oldest
`tag`	string	Nach Tag filtern (z.B. PVP, SURVIVAL)
`country`	string	Nach Ländercode filtern (z.B. US, DE)
`search`	string	Nach Name oder Beschreibung suchen
`online`	boolean	Nur Online-Server filtern

Antwort

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

Detaillierte Informationen zu einem bestimmten Server abrufen

Antwort

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

Echtzeit-Serverstatus abrufen (erfordert status -Berechtigung)

Antwort

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

Fehlerbehandlung

Alle Fehler werden in einem einheitlichen Format zurückgegeben:

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

Häufige Fehlercodes

Code	Beschreibung
`400`	Ungültige Anfrage - Ungültige Parameter
`401`	Nicht autorisiert - Fehlender oder ungültiger API-Schlüssel
`403`	Verboten - Unzureichende Berechtigungen
`404`	Nicht gefunden - Ressource existiert nicht
`429`	Zu viele Anfragen - Ratenbegrenzung überschritten
`500`	Interner Serverfehler

Codebeispiele

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"

Bereit loszulegen?

Erstelle deinen API-Schlüssel und beginne noch heute mit dem Aufbau von Integrationen.

Deinen API-Schlüssel erhalten