Documentazione API VPS, REST API per creare e gestire server

Cosa puoi fare con l'API

L'API è utile quando gestisci molti server o vuoi automatizzare il deployment. Carica gli elenchi di piani, regioni e immagini; quando crei un server, il pagamento viene elaborato e il tuo server viene creato dopo la conferma. Si applicano le stesse regole delle pagine web, quindi i server creati con l'API compaiono anche nell'elenco server del tuo account.

Se è la prima volta, segui passo passo la guida rapida all'API, dalla creazione della chiave al primo server. Questa pagina è il riferimento che raccoglie tutti gli endpoint e i campi.

Indirizzo base

Tutte le richieste si inviano aggiungendo il percorso a questo indirizzo. Corpi di richiesta e risposta sono sempre JSON (UTF-8).

https://helpervps.com/api/v1

Autenticazione

Invia l'header Authorization: Bearer YOUR_API_KEY. Puoi creare una chiave dal menu Chiavi API nel tuo account dopo il primo pagamento; le chiavi iniziano con hvp_. La chiave completa viene mostrata solo una volta, subito dopo la creazione, e creando una nuova chiave quella precedente viene disabilitata immediatamente.

curl https://helpervps.com/api/v1/servers \
  -H "Authorization: Bearer YOUR_API_KEY"

Limiti di richiesta

Codice server

I server si identificano non con un numero ma con un codice come S-7K2M-9QX4-HB3T. Inserisci nel percorso il valore id dell'elenco server o della risposta di creazione. Maiuscole e minuscole non contano.

GET /catalog

Restituisce in una volta piani in vendita (plans), regioni (locations), immagini (images) e opzioni aggiuntive (addons). Tutti i codici da usare per creare un server vengono da qui. monthly è il prezzo mensile in dollari USA, le opzioni non in vendita arrivano come null. monthly_per_gb del disco aggiuntivo è mostrato con tre decimali.

Esempio di richiesta

curl https://helpervps.com/api/v1/catalog \
  -H "Authorization: Bearer YOUR_API_KEY"

Esempio di risposta

{
  "plans": [
    { "code": "s2", "type": "basic", "vcpu": 1, "ram_mb": 2048, "disk_gb": 50, "transfer_tb": 2, "monthly": "2.48" }
  ],
  "locations": ["frankfurt", "singapore", "seoul"],
  "images": ["ubuntu-24-04", "debian-13", "almalinux-10", "app-docker"],
  "addons": {
    "backups": { "percent_of_plan": 5.6 },
    "extra_disk": { "sizes_gb": [50, 100, 250, 500, 1000], "monthly_per_gb": "0.028" },
    "ddos_protection": { "monthly": "1.68" }
  }
}

GET /servers

Restituisce l'elenco dei tuoi server, dal più recente. I server eliminati o non creati sono esclusi.

Esempio di richiesta

curl https://helpervps.com/api/v1/servers \
  -H "Authorization: Bearer YOUR_API_KEY"

Esempio di risposta

[
  {
    "id": "S-7K2M-9QX4-HB3T",
    "label": "web-1",
    "state": "running",
    "ipv4": "192.0.2.15",
    "ipv6": "2001:db8::15",
    "monthly": "2.48",
    "backups": false,
    "extra_disk_gb": 0,
    "ddos_protection": false,
    "paid_until": "2026-11-18T09:00:00.000Z"
  }
]

POST /servers

Crea un server e processa il pagamento. Usa i codici del catalogo per piano, ubicazione e immagine così come sono. label accetta fino a 40 caratteri tra lettere latine, numeri, punti e trattini; gli altri caratteri diventano trattini. backups, extra_disk_gb e ddos_protection sono opzionali. In caso di successo ricevi 201 con i dettagli del server, e root_password è incluso una sola volta in questa risposta (puoi anche visualizzarlo nella pagina del server del tuo account per 7 giorni).

Esempio di richiesta

curl -X POST https://helpervps.com/api/v1/servers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan":"s2","location":"frankfurt","image":"ubuntu-24-04","label":"web-1","backups":true,"extra_disk_gb":0,"ddos_protection":false}'

Esempio di risposta

{
  "id": "S-7K2M-9QX4-HB3T",
  "label": "web-1",
  "state": "creating",
  "ipv4": null,
  "ipv6": null,
  "monthly": "2.61",
  "backups": true,
  "extra_disk_gb": 0,
  "ddos_protection": false,
  "paid_until": "2026-11-18T09:00:00.000Z",
  "root_password": "..."
}

GET /servers/{id}

Restituisce stato, indirizzi, prezzo mensile e scadenza del pagamento di un server. Un nuovo server parte da creating, diventa running quando è pronto e ipv4 e ipv6 vengono compilati. Controllare a intervalli di qualche secondo è più che sufficiente.

Esempio di richiesta

curl https://helpervps.com/api/v1/servers/S-7K2M-9QX4-HB3T \
  -H "Authorization: Bearer YOUR_API_KEY"

Esempio di risposta

{
  "id": "S-7K2M-9QX4-HB3T",
  "label": "web-1",
  "state": "running",
  "ipv4": "192.0.2.15",
  "ipv6": "2001:db8::15",
  "monthly": "2.61",
  "backups": true,
  "extra_disk_gb": 0,
  "ddos_protection": false,
  "paid_until": "2026-11-18T09:00:00.000Z"
}

POST /servers/{id}/start (stop, reboot)

start accende un server fermo (stopped), stop e reboot spengono o riavviano un server in esecuzione (running). La risposta contiene i dati aggiornati del server.

Esempio di richiesta

curl -X POST https://helpervps.com/api/v1/servers/S-7K2M-9QX4-HB3T/reboot \
  -H "Authorization: Bearer YOUR_API_KEY"

Esempio di risposta

{
  "id": "S-7K2M-9QX4-HB3T",
  "label": "web-1",
  "state": "rebooting",
  ...
}

POST /servers/{id}/renew

Paga ora per estendere il periodo di validità. Un server sospeso dopo la scadenza viene riattivato con questa richiesta.

Esempio di richiesta

curl -X POST https://helpervps.com/api/v1/servers/S-7K2M-9QX4-HB3T/renew \
  -H "Authorization: Bearer YOUR_API_KEY"

Esempio di risposta

{
  "id": "S-7K2M-9QX4-HB3T",
  "state": "running",
  "paid_until": "2026-12-18T09:00:00.000Z",
  ...
}

DELETE /servers/{id}

Elimina server e disco. Dalla data di fatturazione successiva non ci sono addebiti; il periodo residuo del mese già pagato non viene rimborsato.

Esempio di richiesta

curl -X DELETE https://helpervps.com/api/v1/servers/S-7K2M-9QX4-HB3T \
  -H "Authorization: Bearer YOUR_API_KEY"

Esempio di risposta

{
  "id": "S-7K2M-9QX4-HB3T",
  "state": "deleted"
}

Campi della risposta server

Valori di stato

Errori

In caso di errore ricevi un codice di stato e un JSON come {"error": "codice"}. Gestisci i casi in base al valore del codice.

Guide utili

I pagamenti avvengono tramite il checkout sicuro di PayGate. Puoi reinstallare e creare una nuova password root nella pagina del server del tuo account; i passaggi sono nella guida alla reinstallazione.

Cosa puoi fare con l'API ed esempi di automazione sono nella pagina VPS API, i prezzi mensili per piano nella pagina prezzi.