Desarrolladores/API REST

Referencia de la API REST

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

Autenticación: envía Authorization: Bearer ptlc_... y Accept: application/json. Crea claves en Cuenta → Claves API. Una clave puede limitarse a ciertas direcciones; consulta la lista de IP permitidas.

La API es compatible con la API de cliente de Pterodactyl, así que las herramientas y bibliotecas de Pterodactyl existentes funcionan con ella. Los endpoints exclusivos de Hostwolf llevan la marca HW.

Convenciones#

Respuestas. Los objetos individuales llegan envueltos como {"object": "server", "attributes": {...}}. Las listas llegan como {"object": "list", "data": [...], "meta": {...}}. Los endpoints exclusivos de Hostwolf devuelven JSON simple.

Paginación. Las listas paginadas aceptan ?page= y ?per_page= (máx. 100 para servidores, 50 para copias de seguridad) y devuelven meta.pagination con total, count, per_page, current_page y total_pages.

Errores.

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

Algunos endpoints de Hostwolf devuelven en su lugar {"error": "...", "code": "..."}, p. ej. 409 downgrade_requires_reset al cambiar un juego a una versión anterior, o 422 unknown_version para una versión que no existe.

Códigos de estado:

• 204: correcto, sin contenido.
• 401: falta la clave, es incorrecta o está revocada.
• 403: falta de permiso (subusuarios), un servidor suspendido o una petición desde una dirección fuera de la lista de IP permitidas de la clave.
• 404: no encontrado.
• 409: el servidor está ocupado (instalando, restaurando o transfiriéndose).
• 422: error de validación.
• 429: límite de peticiones alcanzado. Retry-After indica cuántos segundos esperar; consulta los límites.
• 502: no se puede contactar con el nodo del servidor, o el servidor debe estar encendido.

IDs de servidor. {server} es el identifier del servidor, los 8 caracteres de su URL en el panel. El UUID completo también sirve.

Cuenta#

Servidores#

Archivos#

Todas las rutas son relativas a la raíz del servidor. root es la carpeta donde están las entradas de files.

Copias de seguridad#

Juego, jugadores y diagnóstico HW#

Mods, plugins y modpacks HW#

Programaciones#

Red, bases de datos y subusuarios#

Las bases de datos funcionan en la propia máquina del servidor. El primer POST /databases en un servidor arranca el servicio de bases de datos, lo que tarda unos 40 segundos, y responde 202 Accepted con el estado del servicio ({"object": "hostwolf_database_service", "attributes": {"status": "provisioning", …}}) en lugar de la base de datos. Consulta GET /databases hasta que aparezca, o usa databases.create(id, name, { wait: true }). Las siguientes se crean al momento (200). Los servidores de juego se conectan a host.address (172.18.0.1:3306); remote_address solo funciona desde las remote_ips que permitas, o desde cualquier sitio con remote_anywhere. Consulta la guía de bases de datos.

Extras del servidor HW#

Planes y pedidos HW#

Solo lectura. Los pedidos, cancelaciones y pagos se hacen en el panel.

Consola#

La consola en vivo es un websocket en el nodo donde se ejecuta tu servidor.

1. GET /servers/{server}/websocket devuelve {"data": {"token": "...", "socket": "wss://..."}}.
2. Conéctate a socket con una cabecera Origin: https://panel.hostwolf.net.
3. Envía {"event": "auth", "args": ["<token>"]} y espera a auth success.
4. Envía {"event": "send logs", "args": [null]} para volver a recibir la salida reciente.

Los mensajes son JSON con la forma {"event": "...", "args": [...]}.

Eventos que recibes:

• console output
• status
• stats (una cadena JSON)
• install output
• daemon message y daemon error
• token expiring: pide un token nuevo y vuelve a enviar auth.
• token expired

Eventos que puedes enviar:

• send command con el texto del comando.
• set state con start, stop, restart o kill.
• send logs
• send stats

El SDK se encarga de todo esto: hw.console(id) o hw.tail(id).

SFTP#

También puedes acceder a los archivos por SFTP. Usa la dirección de sftp_details que devuelve GET /servers/{server}, con el usuario <your username>.<server identifier>. Inicia sesión con la contraseña del panel o con una clave SSH añadida en /account/ssh-keys.