Développeurs/API REST

Référence de l’API REST

URL de base : https://panel.hostwolf.net/api/client

Authentification : envoyez Authorization: Bearer ptlc_... et Accept: application/json. Créez des clés dans Compte → Clés API. Une clé peut être limitée à certaines adresses ; voir la liste d’adresses IP autorisées.

L’API est compatible avec l’API client de Pterodactyl, donc les outils et bibliothèques Pterodactyl existants fonctionnent avec elle. Les endpoints propres à Hostwolf sont marqués HW.

Conventions#

Réponses. Les objets seuls arrivent enveloppés sous la forme {"object": "server", "attributes": {...}}. Les listes arrivent sous la forme {"object": "list", "data": [...], "meta": {...}}. Les endpoints propres à Hostwolf renvoient du JSON simple.

Pagination. Les listes paginées acceptent ?page= et ?per_page= (100 max. pour les serveurs, 50 pour les sauvegardes) et renvoient meta.pagination avec total, count, per_page, current_page et total_pages.

Erreurs.

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

Certains endpoints Hostwolf renvoient plutôt {"error": "...", "code": "..."}, par ex. 409 downgrade_requires_reset lors du passage d’un jeu à une version plus ancienne, ou 422 unknown_version pour une version qui n’existe pas.

Codes de statut :

• 204 : succès, sans contenu.
• 401 : clé absente, erronée ou révoquée.
• 403 : permission manquante (sous-utilisateurs), serveur suspendu, ou requête venant d’une adresse hors de la liste d’adresses IP autorisées de la clé.
• 404 : introuvable.
• 409 : le serveur est occupé (installation, restauration ou transfert).
• 422 : erreur de validation.
• 429 : limite de requêtes atteinte. Retry-After indique combien de secondes attendre ; voir les limites.
• 502 : le nœud du serveur est injoignable, ou le serveur doit être démarré.

Identifiants de serveur. {server} est l’identifier du serveur, les 8 caractères de son URL dans le panel. L’UUID complet fonctionne aussi.

Compte#

Serveurs#

Fichiers#

Tous les chemins sont relatifs à la racine du serveur. root est le dossier dans lequel se trouvent les entrées de files.

Sauvegardes#

Jeu, joueurs et diagnostic HW#

Mods, plugins et modpacks HW#

Planifications#

Réseau, bases de données et sous-utilisateurs#

Les bases de données tournent sur la machine du serveur. Le premier POST /databases sur un serveur démarre le service de bases de données, ce qui prend environ 40 secondes, et répond 202 Accepted avec l’état du service ({"object": "hostwolf_database_service", "attributes": {"status": "provisioning", …}}) au lieu de la base. Interrogez GET /databases jusqu’à ce qu’elle apparaisse, ou utilisez databases.create(id, name, { wait: true }). Les bases suivantes sont créées immédiatement (200). Les serveurs de jeu se connectent à host.address (172.18.0.1:3306) ; remote_address ne fonctionne que depuis les remote_ips que vous autorisez, ou depuis n’importe où avec remote_anywhere. Voir le guide des bases de données.

Extras du serveur HW#

Offres et commandes HW#

Lecture seule. Commande, résiliation et paiement se font dans le panel.

Console#

La console en direct est un websocket sur le nœud qui exécute votre serveur.

1. GET /servers/{server}/websocket renvoie {"data": {"token": "...", "socket": "wss://..."}}.
2. Connectez-vous à socket avec un en-tête Origin: https://panel.hostwolf.net.
3. Envoyez {"event": "auth", "args": ["<token>"]} et attendez auth success.
4. Envoyez {"event": "send logs", "args": [null]} pour rejouer la sortie récente.

Les messages sont du JSON de la forme {"event": "...", "args": [...]}.

Événements que vous recevez :

• console output
• status
• stats (une chaîne JSON)
• install output
• daemon message et daemon error
• token expiring : récupérez un nouveau jeton et renvoyez auth.
• token expired

Événements que vous pouvez envoyer :

• send command avec le texte de la commande.
• set state avec start, stop, restart ou kill.
• send logs
• send stats

Le SDK s’occupe de tout cela : hw.console(id) ou hw.tail(id).

SFTP#

Les fichiers sont aussi accessibles en SFTP. Utilisez l’adresse de sftp_details renvoyée par GET /servers/{server}, avec le nom d’utilisateur <your username>.<server identifier>. Connectez-vous avec le mot de passe du panel ou une clé SSH ajoutée dans /account/ssh-keys.