REST-API-Referenz

Basis-URL: https://panel.hostwolf.net/api/client

Authentifizierung: sende Authorization: Bearer ptlc_... und Accept: application/json. Schlüssel erstellst du unter Konto → API-Schlüssel. Ein Schlüssel lässt sich auf bestimmte Adressen beschränken; siehe IP-Freigabeliste.

Die API ist mit der Pterodactyl-Client-API kompatibel, bestehende Pterodactyl-Tools und -Bibliotheken funktionieren also damit. Hostwolf-eigene Endpunkte sind markiert mit HW.

Konventionen#

Antworten. Einzelne Objekte kommen verpackt als {"object": "server", "attributes": {...}}. Listen kommen als {"object": "list", "data": [...], "meta": {...}}. Hostwolf-eigene Endpunkte liefern einfaches JSON.

Paginierung. Paginierte Listen akzeptieren ?page= und ?per_page= (max. 100 für Server, 50 für Backups) und liefern meta.pagination mit total, count, per_page, current_page und total_pages.

Fehler.

{
  "errors": [
    { "code": "ValidationException", "status": "422", "detail": "The name field is required." }
  ]
}

Manche Hostwolf-Endpunkte liefern stattdessen {"error": "...", "code": "..."}, z. B. 409 downgrade_requires_reset beim Wechsel eines Spiels auf eine ältere Version oder 422 unknown_version für eine Version, die es nicht gibt.

Statuscodes:

204: erfolgreich, ohne Inhalt.
401: Schlüssel fehlt, ist falsch oder widerrufen.
403: fehlende Berechtigung (Subuser), ein gesperrter Server oder eine Anfrage von einer Adresse außerhalb der IP-Freigabeliste des Schlüssels.
404: nicht gefunden.
409: der Server ist beschäftigt (Installation, Wiederherstellung oder Umzug).
422: Validierungsfehler.
429: Ratenlimit erreicht. Retry-After gibt die Wartezeit in Sekunden an; siehe Limits.
502: der Node des Servers ist nicht erreichbar oder der Server muss laufen.

Server-IDs. {server} ist der identifier des Servers, die 8 Zeichen in seiner Panel-URL. Die vollständige UUID funktioniert auch.

Konto#

SDK: hw.account · hw.servers.list · Panel: Kontoeinstellungen

Methode	Pfad	Inhalt / Query	Hinweise
GET	`/`	`page`, `per_page`, `filter[*]`, `type`	Deine Server (paginiert)
GET	`/permissions`		Alle Berechtigungsschlüssel für Subuser
GET	`/account`		Dein Konto
PUT	`/account/email`	`email`, `password`
PUT	`/account/password`	`current_password`, `password`, `password_confirmation`
PUT	`/account/profile` HW	`first_name`, `last_name`	Anzeigename
PUT	`/account/language` HW	`language`: `en-GB` `en-US` `de` `fr` `es` `fi`; optional `currency` (`auto`, `USD`, `EUR`…)	Panel-Sprache und Währung der Preise
POST DELETE	`/account/avatar` HW	`image`: Data-URL (PNG/JPEG/WebP, max. 512 KB)	`avatar_url` in `/account` ist danach ein Pfad auf dem Panel
GET	`/account/activity`	`page`, `filter[event]`, `sort`	Paginiert
GET PUT	`/account/notifications` HW	`email_enabled`, `email_address`, `discord_enabled`, `discord_webhook`, `notify_deploy`	Kontoweite Benachrichtigungen
POST	`/account/notifications/test` HW		Sendet einen Test an jeden aktivierten Kanal; `results` ist leer, wenn keiner aktiv ist
GET PUT	`/account/curseforge` HW	`key` (null löscht ihn)	Dein eigener CurseForge-API-Schlüssel
GET PUT	`/account/factorio` HW	`username`, `token`	Zugangsdaten für das Factorio-Mod-Portal
GET	`/account/api-keys`
POST	`/account/api-keys`	`description`, `allowed_ips[]` (IPs oder CIDR-Bereiche, max. 50)	Der Schlüssel ist `attributes.identifier`, gefolgt von `meta.secret_token`; wird nur einmal angezeigt
DELETE	`/account/api-keys/{identifier}`
GET	`/account/ssh-keys`		Für SFTP
POST	`/account/ssh-keys`	`name`, `public_key`
POST	`/account/ssh-keys/remove`	`fingerprint`

Server#

SDK: hw.servers · hw.startup · MCP: list_servers, get_server, power_server, send_command

Methode	Pfad	Inhalt / Query	Hinweise
GET	`/servers/{server}`	`include=egg,subusers`	Details, Zuweisungen, Startvariablen, `region` HW
GET	`/servers/{server}/resources`		`current_state`, CPU, Arbeitsspeicher, Speicherplatz, Netzwerk, Laufzeit
GET	`/servers/{server}/activity`	`page`, `filter[event]`	Paginiert
POST	`/servers/{server}/power`	`signal`: `start` `stop` `restart` `kill`	`204`
POST	`/servers/{server}/command`	`command`	Server muss laufen
GET	`/servers/{server}/websocket`		Konsolen-Token, siehe Konsole
POST	`/servers/{server}/settings/rename`	`name`, `description`
POST	`/servers/{server}/settings/reinstall`		Führt das Installationsskript erneut aus
PUT	`/servers/{server}/settings/docker-image`	`docker_image`	Eines der Images des Eggs
GET	`/servers/{server}/startup`		Variablen, plus `meta.startup_command` und `meta.docker_images`
PUT	`/servers/{server}/startup/variable`	`key`, `value`	`key` ist der Name der Umgebungsvariable, z. B. `MINECRAFT_VERSION`

Dateien#

SDK: hw.files · MCP: list_files, read_file, write_file, delete_files

Alle Pfade sind relativ zum Serververzeichnis. root ist das Verzeichnis, in dem die files-Einträge liegen.

Methode	Pfad	Inhalt / Query	Hinweise
GET	`/servers/{server}/files/list`	`directory`
GET	`/servers/{server}/files/contents`	`file`	Rohtext. Eine fehlende Datei liefert `500` vom Node; das SDK meldet sie als `404`
POST	`/servers/{server}/files/write`	`?file=`; Rohtext als Inhalt	Erstellt oder überschreibt
GET	`/servers/{server}/files/download`	`file`	`attributes.url`: signierte Einmal-URL
GET	`/servers/{server}/files/upload`		Signierte URL: POST multipart `files` an `url&directory=/path`
PUT	`/servers/{server}/files/rename`	`root`, `files[]: {from, to}`	Verschiebt auch
POST	`/servers/{server}/files/copy`	`location`
POST	`/servers/{server}/files/delete`	`root`, `files[]`
POST	`/servers/{server}/files/create-folder`	`root`, `name`
POST	`/servers/{server}/files/compress`	`root`, `files[]`	Liefert das Archiv
POST	`/servers/{server}/files/decompress`	`root`, `file`
POST	`/servers/{server}/files/chmod`	`root`, `files[]: {file, mode}`
POST	`/servers/{server}/files/pull`	`url`, `directory`, `filename`, `use_header`, `foreground`	Server lädt eine URL herunter

Backups#

SDK: hw.backups · MCP: create_backup, restore_backup, list_backups · Limit: 2 Backups pro 10 Minuten.

Methode	Pfad	Inhalt / Query	Hinweise
GET	`/servers/{server}/backups`	`page`, `per_page`	Paginiert
POST	`/servers/{server}/backups`	`name`, `ignored`, `is_locked`	Läuft im Hintergrund
GET	`/servers/{server}/backups/{uuid}`		`completed_at` ist gesetzt, sobald es fertig ist
GET	`/servers/{server}/backups/{uuid}/download`		Signierte URL
POST	`/servers/{server}/backups/{uuid}/lock`		Sperre umschalten
POST	`/servers/{server}/backups/{uuid}/restore`	`truncate`	`truncate: true` löscht vorher alle Dateien
DELETE	`/servers/{server}/backups/{uuid}`
GET PUT	`/servers/{server}/hostwolf/smart-backups` HW	`enabled`	Automatische Backups vor riskanten Änderungen

Spiel, Spieler und Diagnose HW#

SDK: hw.game, hw.players · MCP: diagnose_server, list_players, player_action, get_game_settings

Methode	Pfad	Inhalt / Query	Hinweise
GET	`/servers/{server}/game/versions`		`supported`, `current`, `versions`
POST	`/servers/{server}/game/version`	`version`, `reset_world`, `force`	Wechselt und installiert neu. `409 downgrade_requires_reset` bei älteren Versionen, `422 unknown_version` bei Versionen, die nicht in `/game/versions` stehen
GET	`/servers/{server}/hostwolf/game-settings`		Verständliche Einstellungen, nach Konfigurationsdatei gruppiert. `supported: false` bei Spielen ohne sie, etwa Java-Minecraft (bearbeite dort `server.properties`)
PUT	`/servers/{server}/hostwolf/game-settings`	`values: {id: "value"}`, `restart`	Bool-Werte sind `"true"` / `"false"`
GET	`/servers/{server}/hostwolf/diagnostics`		„Fix my server“-Prüfungen mit Schweregrad
GET	`/servers/{server}/players`		Anzahl online, Maximum, Namen (Minecraft)
GET	`/servers/{server}/hostwolf/players`		Live-Spielerliste über RCON/Query und unterstützte Aktionen
POST	`/servers/{server}/hostwolf/players/{action}`	`player: {name, steamid, id}`, `message`	`action`: `kick` `ban` `unban` `broadcast`

Mods, Plugins und Modpacks HW#

SDK: hw.addons, hw.modpacks · MCP: search_addons, install_addon, install_modpack · Unterstützte Spiele: Spiele

Methode	Pfad	Inhalt / Query	Hinweise
GET	`/servers/{server}/addons`		Unterstützte Quellen, Installationsverzeichnis, Frameworks, Workshop-Modus
GET	`/servers/{server}/addons/search`	`source`, `q`, `page`	Quellen hängen vom Spiel ab: `modrinth`, `curseforge`, `hangar`, `spigot`, `umod`, `thunderstore`…
GET	`/servers/{server}/addons/versions`	`source`, `project`	Markiert kompatible Versionen
POST	`/servers/{server}/addons/install`	`source`, `project`, `version`	`version` weglassen für die neueste kompatible
GET	`/servers/{server}/addons/installed`	`updates=1`	Installierte Addons mit verfügbaren Updates, plus manuelle Dateien
DELETE	`/servers/{server}/addons/installed/{id}`
POST	`/servers/{server}/addons/manual/delete`	`file`	Eine manuell hinzugefügte Datei entfernen
POST	`/servers/{server}/addons/upload`	multipart `file`	z. B. ein Plugin als `.jar`
POST	`/servers/{server}/addons/featured`	`project`	Empfohlene Addons mit einem Klick
PUT	`/servers/{server}/addons/framework`	`framework`	z. B. Oxide/Carbon, BepInEx
POST	`/servers/{server}/addons/cs2`	`repair`	CS2: Metamod + CounterStrikeSharp
GET PUT	`/servers/{server}/addons/workshop`	`items[]`	Steam-Workshop-Inhalte oder -Kollektion
GET	`/servers/{server}/addons/modpacks`		Aktuelles Modpack und Ergebnis des letzten Starts
GET	`/servers/{server}/addons/modpacks/search`	`q`, `page`, `category`, `source`	`source`: `modrinth` oder `curseforge`
GET	`/servers/{server}/addons/modpacks/versions`	`project`, `source`
POST	`/servers/{server}/addons/modpacks`	`project`, `version`, `fresh_world`, `source`	Ersetzt Mods und Loader. `404`, wenn das Projekt oder die Version nicht existiert
DELETE	`/servers/{server}/addons/modpacks`

Zeitpläne#

SDK: hw.schedules · MCP: create_schedule, list_schedules

Methode	Pfad	Inhalt / Query	Hinweise
GET	`/servers/{server}/schedules`		Enthält die Aufgaben
POST	`/servers/{server}/schedules`	`name`, `minute`, `hour`, `day_of_month`, `month`, `day_of_week`, `is_active`, `only_when_online`	Cron-Felder, UTC
GET POST DELETE	`/servers/{server}/schedules/{id}`	wie beim Erstellen	POST aktualisiert
POST	`/servers/{server}/schedules/{id}/execute`		Jetzt ausführen
POST	`/servers/{server}/schedules/{id}/tasks`	`action` (`command` `power` `backup`), `payload`, `time_offset`, `continue_on_failure`
POST DELETE	`/servers/{server}/schedules/{id}/tasks/{task}`	wie beim Erstellen	POST aktualisiert

Netzwerk, Datenbanken und Subuser#

SDK: hw.network, hw.databases, hw.users

Methode	Pfad	Inhalt / Query	Hinweise
GET	`/servers/{server}/network/allocations`		Ports
POST	`/servers/{server}/network/allocations`		Weiteren Port automatisch zuweisen (sofern der Tarif es erlaubt)
POST	`/servers/{server}/network/allocations/{id}`	`notes`
POST	`/servers/{server}/network/allocations/{id}/primary`
DELETE	`/servers/{server}/network/allocations/{id}`
GET	`/servers/{server}/databases`	`include=password`	Außerdem `on_node`, `remote_ips`, `remote_anywhere`, `remote_address`
GET	`/servers/{server}/databases/service` HW		`status` (`none` `provisioning` `ready` `unreachable` `failed`), `local_address`, `public_address`, `other_servers`
POST	`/servers/{server}/databases`	`database`, `remote_ips[]`, `remote_anywhere`	`202` mit dem Dienststatus, während die erste Datenbank startet (siehe unten)
POST	`/servers/{server}/databases/{id}/rotate-password`
POST	`/servers/{server}/databases/{id}/remote` HW	`remote_ips[]` (öffentliche IPv4, max. 10), `remote_anywhere`	Ersetzt die Liste; `[]` schließt den Zugriff von außen
GET	`/servers/{server}/databases/{id}/export` HW		`.sql.gz`-Download. 6 pro Minute
POST	`/servers/{server}/databases/{id}/import` HW	`file` (multipart, `.sql` oder `.sql.gz`, max. 50 MB)	`204`. 6 pro Minute
DELETE	`/servers/{server}/databases/{id}`
GET	`/servers/{server}/users`		Subuser
POST	`/servers/{server}/users`	`public_id`, `permissions[]`	Fügt ein bestehendes Hostwolf-Konto über seine öffentliche ID hinzu (`HW-XXXXXX`, auf dessen Kontoseite)
GET POST DELETE	`/servers/{server}/users/{uuid}`	`permissions[]`	POST aktualisiert

Datenbanken laufen auf dem eigenen Rechner des Servers. Das erste POST /databases auf einem Server startet den Datenbankdienst, was etwa 40 Sekunden dauert, und antwortet statt mit der Datenbank mit 202 Accepted und dem Dienststatus ({"object": "hostwolf_database_service", "attributes": {"status": "provisioning", …}}). Frage GET /databases ab, bis sie erscheint, oder nutze databases.create(id, name, { wait: true }). Weitere Datenbanken werden sofort angelegt (200). Gameserver verbinden sich mit host.address (172.18.0.1:3306); remote_address funktioniert nur von den remote_ips, die du erlaubst, oder von überall mit remote_anywhere. Siehe die Datenbank-Anleitung.

Server-Extras HW#

SDK: hw.notifications, hw.domain, hw.mcNetwork

Methode	Pfad	Inhalt / Query	Hinweise
GET PUT	`/servers/{server}/hostwolf/notifications`	`webhook_url`, `clear_webhook`, `events`	Discord-Benachrichtigungen: gestartet, gestoppt, abgestürzt, Backups, Spieler
POST	`/servers/{server}/hostwolf/notifications/test`
GET	`/servers/{server}/hostwolf/domain`		Eigene Domain und die nötigen DNS-Einträge
POST	`/servers/{server}/hostwolf/domain/check`	`hostname`	Prüft das aktuelle DNS
PUT DELETE	`/servers/{server}/hostwolf/domain`	`hostname`
GET	`/servers/{server}/hostwolf/network`		Auf einem Velocity/BungeeCord-Proxy: seine Einträge und die Server, die du verbinden kannst
POST	`/servers/{server}/hostwolf/network/link`	`servers[]: {id, key}`, `lobby`, `restart`
POST	`/servers/{server}/hostwolf/network/unlink`	`id`, `restart`
POST	`/servers/{server}/hostwolf/network/fabric-proxy`	`id`	Installiert FabricProxy-Lite auf einem Fabric-Backend

Tarife und Bestellungen HW#

SDK: hw.store · MCP: get_plans_and_prices, list_orders · Preise zum Lesen: Preise

Nur lesend. Bestellung, Kündigung und Zahlung laufen über das Panel.

Methode	Pfad	Hinweise
GET	`/store/catalog`	Spiele, Tarifgrößen, Regionen und aktuelle Preise je Region
GET	`/store/orders`	Offene, aktive und kürzlich fehlgeschlagene Bestellungen
GET	`/store/billing`	Alle Bestellungen mit Preis, Verlängerung, Kündigung und Erstattungsstatus

Konsole#

SDK: hw.console(), hw.tail() · MCP: get_console

Die Live-Konsole ist ein Websocket auf dem Node, auf dem dein Server läuft.

GET /servers/{server}/websocket liefert {"data": {"token": "...", "socket": "wss://..."}}.
Verbinde dich mit socket und einem Header Origin: https://panel.hostwolf.net.
Sende {"event": "auth", "args": ["<token>"]} und warte auf auth success.
Sende {"event": "send logs", "args": [null]}, um die letzten Ausgaben erneut zu erhalten.

Nachrichten sind JSON in der Form {"event": "...", "args": [...]}.

Events, die du empfängst:

console output
status
stats (ein JSON-String)
install output
daemon message und daemon error
token expiring: neues Token holen und auth erneut senden.
token expired

Events, die du senden kannst:

send command mit dem Befehlstext.
set state mit start, stop, restart oder kill.
send logs
send stats

Das SDK übernimmt das alles: hw.console(id) oder hw.tail(id).

SFTP#

Dateien sind auch per SFTP erreichbar. Verwende die Adresse aus sftp_details von GET /servers/{server} mit dem Benutzernamen <your username>.<server identifier>. Melde dich mit deinem Panel-Passwort oder einem SSH-Schlüssel an, den du unter /account/ssh-keys hinzugefügt hast.

Hängst du fest oder fehlt ein Endpunkt? Schreib uns unter game.hostwolf.net/contact oder support@hostwolf.net.