Gestiona tu VPS con la API REST y curl: estado, encendido, reinstalación, renovación

Pedir un servidor por la API cuesta una petición. Eso está en Pide un VPS en 4 llamadas a la API. Esta página trata de todo lo que viene después: las acciones rutinarias que harías con clics en el panel, escritas como comandos curl que puedes pegar en un script.

Cada comando de abajo se ejecutó contra nuestra API antes de publicar, y las respuestas son copias recortadas de lo que devolvió.

Preparación

Dos variables mantienen los comandos cortos:

export API=https://api.eqvps.com/api/v1/eqvps
export EQVPS_TOKEN='paste-your-token-here'

El token sale de POST /auth/register o de Settings → API tokens en el panel. Mantenlo fuera del historial de la shell si otras personas usan la máquina; leerlo de un archivo con export EQVPS_TOKEN=$(cat ~/.eqvps_token) basta.

Encuentra tus servidores

curl -s $API/services -H "Authorization: Bearer $EQVPS_TOKEN"

Cada entrada tiene un id como 47HZ7YF. Es el código de servicio que piden todas las demás llamadas. Después, el panorama completo de un servidor:

curl -s $API/services/47HZ7YF -H "Authorization: Bearer $EQVPS_TOKEN"

{ "data": {
    "id": "47HZ7YF", "status": "active", "queued": false,
    "product": { "slug": "nano", "name": "Nano" },
    "specs": { "vcpu": 2, "memory_mb": 1024, "disk_gb": 15 },
    "hostname": "agent-box",
    "vm": { "state": "running", "uptime": 5340 },
    "access": { "method": "ssh", "host": "203.0.113.10", "port": 21521, "user": "root", "nat": true, ... } } }

access te dice cómo entrar. En un plan con IPv4 propia el puerto es 22; en un plan NAT es tu puerto reenviado personal. Esta llamada solo lee, así que consultarla en bucle es seguro.

Si pediste sin clave SSH, la contraseña de root se muestra una vez:

curl -s "$API/services/47HZ7YF?reveal=1" -H "Authorization: Bearer $EQVPS_TOKEN"

Mientras el servidor sigue arrancando, la respuesta dice password_pending y la revelación única no se gasta. Espera medio minuto y vuelve a preguntar.

Encendido: start, stop, reboot

curl -s -X POST $API/services/47HZ7YF/power \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"action": "reboot"}'

action es start, stop o reboot. Un servidor que aún no está activo (todavía se está creando, o suspendido por impago) responde 409 Service is not active. No es un error de tu script. Comprueba status primero.

Métricas

curl -s "$API/services/47HZ7YF/metrics?timeframe=day" -H "Authorization: Bearer $EQVPS_TOKEN"

CPU, memoria, red y disco como serie temporal. timeframe es hour (por defecto), day, week o month. Útil para un cron que te avise cuando el disco no para de crecer. Los contadores de tráfico del periodo de facturación actual están en Comprobar velocidad y tráfico.

Renombrar el servidor

curl -s -X POST $API/services/47HZ7YF/hostname \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"hostname": "web-01"}'

El agente invitado aplica el nuevo nombre dentro del sistema en marcha, sin reiniciar en Linux. Si el servidor está detenido, o quitaste qemu-guest-agent, la llamada devuelve 409 agent_unavailable y no cambia nada.

Reinstalar el SO

Esta borra el disco. La API te obliga a escribir el hostname actual del servidor en confirm, así un script con un id de servicio equivocado no puede borrar la máquina equivocada:

curl -s -X POST $API/services/47HZ7YF/reinstall \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"os_id": 4, "confirm": "web-01"}'

os_id sale de la lista available_os de tu plan en GET /products o de los detalles del propio servidor. La reinstalación corre en segundo plano; consulta GET /services/{id} hasta que status vuelva a ser active.

Renovación y saldo

Los servidores se renuevan cada mes con tu saldo prepago. Para ver cuánto cuestan plazos más largos para este servidor:

curl -s $API/services/47HZ7YF/renew-options -H "Authorization: Bearer $EQVPS_TOKEN"

Para pagar por adelantado, digamos tres meses, en una llamada:

curl -s -X POST $API/services/47HZ7YF/renew \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"months": 3}'

months es 1, 3, 6 o 12, y 12 se cobra al precio anual con su descuento. La respuesta dice paid_from_balance: true y da la nueva fecha de vencimiento. Si el saldo no cubre el importe, no se cobra nada: recibes paid_from_balance: false y una checkout_url para esa factura. Una vez recargado el saldo, POST $API/invoices/{invoice_id}/pay paga esa factura con el saldo; si aún no alcanza, devuelve el mismo tipo de checkout_url y no cobra nada. Consultar y recargar el saldo:

curl -s $API/balance -H "Authorization: Bearer $EQVPS_TOKEN"

curl -s -X POST $API/balance/topup \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"amount": 25}'

La respuesta de recarga contiene una checkout_url. Es un pago cripto: USDT, USDC o ETH en Base, Ethereum o Polygon. El saldo se acredita cuando el pago se confirma en la cadena. Pagar es el único paso que un script no puede hacer por ti, salvo que tenga una billetera.

Monero también funciona, pero solo como recarga de saldo con verificación manual: envías XMR, nos das el id de la transacción y lo acreditamos tras verificarlo. Mira Pagar con Monero.

Cancelar, y cambiar de opinión

La cancelación segura mantiene el servidor en marcha hasta que termina el periodo pagado y simplemente no lo renueva:

curl -s -X POST $API/services/47HZ7YF/cancel \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"type": "end_of_period", "reason": "moving the project elsewhere"}'

reason es obligatorio. Unas pocas palabras bastan. ¿Cambiaste de opinión antes de la fecha?

curl -s -X POST $API/services/47HZ7YF/cancel/undo -H "Authorization: Bearer $EQVPS_TOKEN"

También existe "type": "immediate". Borra el servidor y sus datos al instante, necesita "confirm": "<hostname>" y no se puede deshacer. Salvo que lo digas en serio, usa end_of_period.

Mantén vivo el token

Los tokens nuevos duran un año por defecto. Cada respuesta autenticada lleva una cabecera X-Token-Expires-At, así un script puede notarlo con tiempo. Cambia el token por uno nuevo:

curl -s -X POST $API/auth/token/refresh -H "Authorization: Bearer $EQVPS_TOKEN"

El token antiguo deja de funcionar al instante, así que guarda el nuevo antes de hacer cualquier otra cosa.

Errores que conviene manejar

¿Lo haces desde un cliente de IA en lugar de un script? Las mismas acciones existen como herramientas MCP — mira Cómo un agente gestiona su propio VPS por MCP y la referencia de la API. Si aún no tienes servidor, elige un plan.