Gestire il VPS con l'API REST e curl: stato, alimentazione, reinstallazione, rinnovo

Ordinare un server tramite API richiede una richiesta. È spiegato in Ordinare un VPS in 4 chiamate API. Questa pagina riguarda tutto ciò che viene dopo: le azioni di routine che altrimenti faresti con dei clic nel pannello, scritte come comandi curl da incollare in uno script.

Ogni comando qui sotto è stato eseguito contro la nostra API prima della pubblicazione, e le risposte sono copie accorciate di ciò che è tornato.

Preparazione

Due variabili tengono corti i comandi:

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

Il token arriva da POST /auth/register o da Settings → API tokens nel pannello. Tienilo fuori dalla cronologia della shell se altre persone usano la macchina; leggerlo da un file con export EQVPS_TOKEN=$(cat ~/.eqvps_token) è sufficiente.

Trovare i tuoi server

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

Ogni voce ha un id come 47HZ7YF. È il codice del servizio che tutte le altre chiamate richiedono. Poi il quadro completo di un server:

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 ti dice come entrare. Su un piano con IPv4 propria la porta è 22; su un piano NAT è la tua porta inoltrata personale. Questa chiamata legge soltanto, quindi interrogarla in un ciclo è sicuro.

Se hai ordinato senza chiave SSH, la password di root viene mostrata una volta:

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

Finché il server si sta ancora avviando, la risposta dice password_pending e la visualizzazione unica non viene consumata. Aspetta mezzo minuto e richiedi.

Alimentazione: 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 è start, stop o reboot. Un server non ancora attivo (ancora in creazione, o sospeso per mancato pagamento) risponde 409 Service is not active. Non è un errore del tuo script. Controlla prima status.

Metriche

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

CPU, memoria, rete e disco come serie temporale. timeframe è hour (predefinito), day, week o month. Utile per un cron che ti avvisa quando il disco continua a crescere. I contatori di traffico del periodo di fatturazione corrente sono in Controllare velocità e traffico.

Rinominare il server

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

Il nuovo nome viene applicato nel sistema in esecuzione dall'agente guest, senza riavvio su Linux. Se il server è fermo, o hai rimosso qemu-guest-agent, la chiamata restituisce 409 agent_unavailable e non cambia nulla.

Reinstallare il sistema

Questa cancella il disco. L'API ti obbliga a scrivere l'hostname attuale del server in confirm, così uno script con l'id di servizio sbagliato non può cancellare la macchina sbagliata:

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 viene dalla lista available_os del tuo piano in GET /products o dai dettagli del server stesso. La reinstallazione gira in background; interroga GET /services/{id} finché status non torna active.

Rinnovo e saldo

I server si rinnovano ogni mese dal tuo saldo prepagato. Per vedere quanto costano periodi più lunghi per questo server:

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

Per pagare in anticipo, diciamo tre mesi, con una chiamata:

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

months è 1, 3, 6 o 12, e 12 è fatturato al prezzo annuale con il suo sconto. La risposta dice paid_from_balance: true e indica la nuova scadenza. Se il saldo non copre l'importo, non viene addebitato nulla: ricevi paid_from_balance: false e una checkout_url per quella fattura. Una volta ricaricato il saldo, POST $API/invoices/{invoice_id}/pay paga quella fattura dal saldo; se ancora non basta, restituisce lo stesso tipo di checkout_url e non addebita nulla. Controllare e ricaricare il 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 risposta della ricarica contiene una checkout_url. È un pagamento cripto: USDT, USDC o ETH su Base, Ethereum o Polygon. Il saldo viene accreditato quando il pagamento è confermato on-chain. Pagare è l'unico passo che uno script non può fare al posto tuo, a meno che non abbia un wallet.

Funziona anche Monero, ma solo come ricarica del saldo con verifica manuale: invii XMR, comunichi l'id della transazione e accreditiamo dopo la verifica. Vedi Pagare con Monero.

Disdire, e cambiare idea

La disdetta sicura lascia il server acceso fino alla fine del periodo pagato e semplicemente non lo rinnova:

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 è obbligatorio. Bastano poche parole. Hai cambiato idea prima della data?

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

Esiste anche "type": "immediate". Cancella subito il server e i suoi dati, richiede "confirm": "<hostname>" e non si può annullare. A meno che tu non lo voglia davvero, usa end_of_period.

Mantenere vivo il token

I nuovi token durano un anno per impostazione predefinita. Ogni risposta autenticata porta un'intestazione X-Token-Expires-At, così uno script può accorgersene in anticipo. Scambia il token con uno nuovo:

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

Il vecchio token smette di funzionare subito, quindi salva quello nuovo prima di fare qualsiasi altra cosa.

Errori da gestire

Lo fai da un client IA invece che da uno script? Le stesse azioni esistono come strumenti MCP — vedi Come un agente gestisce il proprio VPS via MCP e il riferimento API. Non hai ancora un server? Scegli un piano.