Documentazione API L'alojamento web accessibile a tutti Visitate LWS

Elencare i VPS

GET /api/v1/servers

operationIdgetServers

Livello richiesto
Sola lettura
Quota
lettura, 3.600 chiamate all'ora

Inventario dei VPS coperti dalla chiave. Lo stato di alimentazione viene letto sull'hypervisor; se questo è momentaneamente irraggiungibile, status vale unavailable e il resto della scheda rimane utilizzabile.

Durante un intervento annunciato da LWS sul server host (aggiornamento, riavvio…), maintenance ne indica la natura e gli orari, che sia programmato o in corso. Se il server host non risponde più durante l'intervento, status vale maintenance: un'indisponibilità prevista e temporanea, non un guasto.

Il filtro status si applica alla pagina richiesta: meta descrive l'inventario completo, non filtrato, e una pagina filtrata può quindi contenere meno voci di per_page.

Lo stato letto sull'hypervisor viene memorizzato nella cache per 15 secondi: una chiamata più ravvicinata restituisce lo stesso valore. Qualsiasi scrittura effettuata tramite l'API su un VPS ne aggiorna subito lo stato.

Parametri di query

page integer facoltativo

Pagina richiesta. Un valore inferiore a 1 viene riportato a 1.

almeno 1

per_page integer facoltativo

Dimensione della pagina. Un valore superiore a 100 viene riportato a 100; un valore nullo, negativo o non numerico, a 25.

al massimo 100 almeno 1

status string facoltativo

Mantenere solo i VPS in questo stato (applicato alla pagina restituita).

uno di: running, stopped, unavailable, maintenance

Risposte

200

Una pagina dell'inventario

{
  "data": [
    {
      "vmid": "116807",
      "name": "vps116807",
      "node": "shp-40",
      "status": "running",
      "maintenance": null,
      "os_template": "debian12_64",
      "commercial_name": "Debian 12",
      "ipv4": "31.207.34.214",
      "ipv6": "2a00:7ee0:9:1:11:6807:1:1",
      "additional_ips": [
        "51.83.12.98"
      ],
      "datacenter": {
        "code": "SJ1",
        "city": "Nancy",
        "country": "France",
        "zone": "eu-france-est"
      },
      "purchased_at": "2025-03-14T00:00:00+01:00",
      "expires_at": "2027-03-14T00:00:00+01:00",
      "enabled": true,
      "expired": false,
      "comment": null
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1
  }
}
Campi della risposta 30
  • data object[]
    obbligatorio
  • vmid string

    Identificativo del VPS

    Esempio: 116807

  • name string

    Nome della macchina sull'hypervisor

  • node string

    Hypervisor che ospita il VPS, a titolo informativo. Mai richiesto in input e soggetto a cambiare in caso di migrazione.

  • status string

    Stato di alimentazione; unavailable se l'hypervisor non ha risposto; maintenance se non risponde durante un intervento annunciato da LWS

    uno di: running, stopped, unavailable, maintenance Esempio: running

  • maintenance object

    Intervento annunciato da LWS sul server host (stato dei servizi), programmato o in corso, che il server risponda o meno; null se non ce ne sono

  • status string

    scheduled: programmato; in_progress: in corso

    uno di: scheduled, in_progress

  • kind string

    works: manutenzione, miglioramento o riavvio; incident: incidente, disservizio, rallentamento o attacco

    uno di: works, incident

  • starts_at string (date-time)
  • expected_end string (date-time)

    Fine prevista; sempre null per un incidente

  • os_template string
  • commercial_name string
  • ipv4 string
  • ipv6 string
  • additional_ips string[]
  • datacenter object
  • code string

    Esempio: SJ1

  • city string

    Esempio: Nancy

  • country string

    Esempio: France

  • zone string

    Esempio: eu-france-est

  • purchased_at string (date-time)
  • expires_at string (date-time)
  • enabled boolean

    false: servizio disattivato

  • expired boolean

    true: servizio scaduto

  • comment string

    Commento inserito nel pannello

  • meta object

    Paginazione. Gli elenchi non paginati restituiscono tutto e meta riflette il numero restituito.

    PaginationMeta

    obbligatorio
  • page integer (int64)

    Pagina restituita

    Esempio: 1

  • per_page integer (int64)

    Dimensione della pagina

    Esempio: 25

  • total integer (int64)

    Numero totale di elementi

    Esempio: 887

  • total_pages integer (int64)

    Numero totale di pagine

    Esempio: 36

400

Parametri non validi: validation_failed — status non previsto.

{
  "type": "https://docs.lws.fr/kvm/errors/validation-failed",
  "title": "Paramètres invalides",
  "status": 400,
  "code": "validation_failed",
  "detail": "Paramètre « status » invalide.",
  "request_id": "3f9a1c07b2e45d18",
  "errors": {
    "status": "Valeurs acceptées : running, stopped, unavailable, maintenance."
  }
}
Campi della risposta 18
  • type string (uri)

    Esempio: https://docs.lws.fr/kvm/errors/vm-not-found

    obbligatorio
  • title string

    Titolo breve

    Esempio: VPS introuvable

    obbligatorio
  • status integer (int64)

    Stato HTTP

    Esempio: 404

    obbligatorio
  • code string

    Codice macchina stabile (vedere «Errori» in Per iniziare)

    Esempio: vm_not_found

    obbligatorio
  • detail string

    Messaggio dettagliato

    Esempio: Aucun VPS 999999 sur ce compte.

    obbligatorio
  • request_id string

    Identificativo della richiesta, da comunicare al supporto

    Esempio: 3f9a1c07b2e45d18

    obbligatorio
  • errors object

    validation_failed: messaggio per ogni parametro errato

  • required_level string

    insufficient_scope: livello richiesto dall'operazione

    uno di: read, exploitation, full

  • task_id string

    task_already_running: task in corso su questo VPS

    Esempio: tsk_000002d5

  • family string

    rate_limited: famiglia di quota esaurita

    uno di: read, mutation, heavy

  • limit integer (int64)

    rate_limited: limite orario della famiglia

  • retry_after integer (int64)

    rate_limited: secondi da attendere

  • lock string

    server_locked: blocco impostato dall'hypervisor (backup, snapshot, suspended…)

    Esempio: snapshot

  • reason string

    server_locked: operation_in_progress, è in corso un'operazione, riprovi dopo Retry-After; suspended, il VPS è in ibernazione, lo avvii prima; support_notified, blocco anomalo, il team LWS è stato avvisato e sta intervenendo

    uno di: operation_in_progress, suspended, support_notified

  • maintenance object

    server_maintenance: natura dell'intervento, inizio e fine prevista (null per un incidente)

  • kind string

    uno di: works, incident

  • started_at string (date-time)
  • expected_end string (date-time)
401

Autenticazione rifiutata: invalid_token — intestazione Authorization assente o non valida, oppure chiave sconosciuta; access_disabled — accesso API disattivato per questo account, oppure servizio API momentaneamente sospeso da LWS.

intestazione Authorization assente o non valida, oppure chiave sconosciuta

{
  "type": "https://docs.lws.fr/kvm/errors/invalid-token",
  "title": "Authentification invalide",
  "status": 401,
  "code": "invalid_token",
  "detail": "Clé inconnue ou révoquée.",
  "request_id": "3f9a1c07b2e45d18"
}

accesso API disattivato per questo account, oppure servizio API momentaneamente sospeso da LWS

{
  "type": "https://docs.lws.fr/kvm/errors/access-disabled",
  "title": "Accès API désactivé",
  "status": 401,
  "code": "access_disabled",
  "detail": "L'accès API est désactivé pour ce compte. Réactivez-le depuis la page « API / MCP » du panel.",
  "request_id": "3f9a1c07b2e45d18"
}
Campi della risposta 18
  • type string (uri)

    Esempio: https://docs.lws.fr/kvm/errors/vm-not-found

    obbligatorio
  • title string

    Titolo breve

    Esempio: VPS introuvable

    obbligatorio
  • status integer (int64)

    Stato HTTP

    Esempio: 404

    obbligatorio
  • code string

    Codice macchina stabile (vedere «Errori» in Per iniziare)

    Esempio: vm_not_found

    obbligatorio
  • detail string

    Messaggio dettagliato

    Esempio: Aucun VPS 999999 sur ce compte.

    obbligatorio
  • request_id string

    Identificativo della richiesta, da comunicare al supporto

    Esempio: 3f9a1c07b2e45d18

    obbligatorio
  • errors object

    validation_failed: messaggio per ogni parametro errato

  • required_level string

    insufficient_scope: livello richiesto dall'operazione

    uno di: read, exploitation, full

  • task_id string

    task_already_running: task in corso su questo VPS

    Esempio: tsk_000002d5

  • family string

    rate_limited: famiglia di quota esaurita

    uno di: read, mutation, heavy

  • limit integer (int64)

    rate_limited: limite orario della famiglia

  • retry_after integer (int64)

    rate_limited: secondi da attendere

  • lock string

    server_locked: blocco impostato dall'hypervisor (backup, snapshot, suspended…)

    Esempio: snapshot

  • reason string

    server_locked: operation_in_progress, è in corso un'operazione, riprovi dopo Retry-After; suspended, il VPS è in ibernazione, lo avvii prima; support_notified, blocco anomalo, il team LWS è stato avvisato e sta intervenendo

    uno di: operation_in_progress, suspended, support_notified

  • maintenance object

    server_maintenance: natura dell'intervento, inizio e fine prevista (null per un incidente)

  • kind string

    uno di: works, incident

  • started_at string (date-time)
  • expected_end string (date-time)
403

Accesso negato: ip_not_allowed — indirizzo di chiamata non autorizzato.

{
  "type": "https://docs.lws.fr/kvm/errors/ip-not-allowed",
  "title": "Adresse non autorisée",
  "status": 403,
  "code": "ip_not_allowed",
  "detail": "L'adresse 203.0.113.10 ne figure pas parmi les adresses autorisées de ce compte.",
  "request_id": "3f9a1c07b2e45d18"
}
Campi della risposta 18
  • type string (uri)

    Esempio: https://docs.lws.fr/kvm/errors/vm-not-found

    obbligatorio
  • title string

    Titolo breve

    Esempio: VPS introuvable

    obbligatorio
  • status integer (int64)

    Stato HTTP

    Esempio: 404

    obbligatorio
  • code string

    Codice macchina stabile (vedere «Errori» in Per iniziare)

    Esempio: vm_not_found

    obbligatorio
  • detail string

    Messaggio dettagliato

    Esempio: Aucun VPS 999999 sur ce compte.

    obbligatorio
  • request_id string

    Identificativo della richiesta, da comunicare al supporto

    Esempio: 3f9a1c07b2e45d18

    obbligatorio
  • errors object

    validation_failed: messaggio per ogni parametro errato

  • required_level string

    insufficient_scope: livello richiesto dall'operazione

    uno di: read, exploitation, full

  • task_id string

    task_already_running: task in corso su questo VPS

    Esempio: tsk_000002d5

  • family string

    rate_limited: famiglia di quota esaurita

    uno di: read, mutation, heavy

  • limit integer (int64)

    rate_limited: limite orario della famiglia

  • retry_after integer (int64)

    rate_limited: secondi da attendere

  • lock string

    server_locked: blocco impostato dall'hypervisor (backup, snapshot, suspended…)

    Esempio: snapshot

  • reason string

    server_locked: operation_in_progress, è in corso un'operazione, riprovi dopo Retry-After; suspended, il VPS è in ibernazione, lo avvii prima; support_notified, blocco anomalo, il team LWS è stato avvisato e sta intervenendo

    uno di: operation_in_progress, suspended, support_notified

  • maintenance object

    server_maintenance: natura dell'intervento, inizio e fine prevista (null per un incidente)

  • kind string

    uno di: works, incident

  • started_at string (date-time)
  • expected_end string (date-time)
429

Quota superata: rate_limited — quota oraria della famiglia esaurita.

{
  "type": "https://docs.lws.fr/kvm/errors/rate-limited",
  "title": "Quota dépassé",
  "status": 429,
  "code": "rate_limited",
  "detail": "Quota dépassé pour les opérations de type « read » : 3600 appels par heure. Réessayez dans 37 seconde(s).",
  "request_id": "3f9a1c07b2e45d18",
  "family": "read",
  "limit": 3600,
  "retry_after": 37
}
Campi della risposta 18
  • type string (uri)

    Esempio: https://docs.lws.fr/kvm/errors/vm-not-found

    obbligatorio
  • title string

    Titolo breve

    Esempio: VPS introuvable

    obbligatorio
  • status integer (int64)

    Stato HTTP

    Esempio: 404

    obbligatorio
  • code string

    Codice macchina stabile (vedere «Errori» in Per iniziare)

    Esempio: vm_not_found

    obbligatorio
  • detail string

    Messaggio dettagliato

    Esempio: Aucun VPS 999999 sur ce compte.

    obbligatorio
  • request_id string

    Identificativo della richiesta, da comunicare al supporto

    Esempio: 3f9a1c07b2e45d18

    obbligatorio
  • errors object

    validation_failed: messaggio per ogni parametro errato

  • required_level string

    insufficient_scope: livello richiesto dall'operazione

    uno di: read, exploitation, full

  • task_id string

    task_already_running: task in corso su questo VPS

    Esempio: tsk_000002d5

  • family string

    rate_limited: famiglia di quota esaurita

    uno di: read, mutation, heavy

  • limit integer (int64)

    rate_limited: limite orario della famiglia

  • retry_after integer (int64)

    rate_limited: secondi da attendere

  • lock string

    server_locked: blocco impostato dall'hypervisor (backup, snapshot, suspended…)

    Esempio: snapshot

  • reason string

    server_locked: operation_in_progress, è in corso un'operazione, riprovi dopo Retry-After; suspended, il VPS è in ibernazione, lo avvii prima; support_notified, blocco anomalo, il team LWS è stato avvisato e sta intervenendo

    uno di: operation_in_progress, suspended, support_notified

  • maintenance object

    server_maintenance: natura dell'intervento, inizio e fine prevista (null per un incidente)

  • kind string

    uno di: works, incident

  • started_at string (date-time)
  • expected_end string (date-time)
502

Dipendenza irraggiungibile: upstream_unavailable — inventario dei VPS momentaneamente non disponibile.

{
  "type": "https://docs.lws.fr/kvm/errors/upstream-unavailable",
  "title": "Service momentanément indisponible",
  "status": 502,
  "code": "upstream_unavailable",
  "detail": "Inventaire des VM indisponible.",
  "request_id": "3f9a1c07b2e45d18"
}
Campi della risposta 18
  • type string (uri)

    Esempio: https://docs.lws.fr/kvm/errors/vm-not-found

    obbligatorio
  • title string

    Titolo breve

    Esempio: VPS introuvable

    obbligatorio
  • status integer (int64)

    Stato HTTP

    Esempio: 404

    obbligatorio
  • code string

    Codice macchina stabile (vedere «Errori» in Per iniziare)

    Esempio: vm_not_found

    obbligatorio
  • detail string

    Messaggio dettagliato

    Esempio: Aucun VPS 999999 sur ce compte.

    obbligatorio
  • request_id string

    Identificativo della richiesta, da comunicare al supporto

    Esempio: 3f9a1c07b2e45d18

    obbligatorio
  • errors object

    validation_failed: messaggio per ogni parametro errato

  • required_level string

    insufficient_scope: livello richiesto dall'operazione

    uno di: read, exploitation, full

  • task_id string

    task_already_running: task in corso su questo VPS

    Esempio: tsk_000002d5

  • family string

    rate_limited: famiglia di quota esaurita

    uno di: read, mutation, heavy

  • limit integer (int64)

    rate_limited: limite orario della famiglia

  • retry_after integer (int64)

    rate_limited: secondi da attendere

  • lock string

    server_locked: blocco impostato dall'hypervisor (backup, snapshot, suspended…)

    Esempio: snapshot

  • reason string

    server_locked: operation_in_progress, è in corso un'operazione, riprovi dopo Retry-After; suspended, il VPS è in ibernazione, lo avvii prima; support_notified, blocco anomalo, il team LWS è stato avvisato e sta intervenendo

    uno di: operation_in_progress, suspended, support_notified

  • maintenance object

    server_maintenance: natura dell'intervento, inizio e fine prevista (null per un incidente)

  • kind string

    uno di: works, incident

  • started_at string (date-time)
  • expected_end string (date-time)
Mostra gli esempi di codice e la console di test
GET /servers
LWS_API_KEY='…'curl -X GET \  "https://panelkvm.lwspanel.com/api/v1/servers" \  -H "Authorization: Bearer $LWS_API_KEY"
$lwsApiKey = '…';$ch = curl_init("https://panelkvm.lwspanel.com/api/v1/servers");curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);curl_setopt($ch, CURLOPT_HTTPHEADER, [    "Authorization: Bearer " . $lwsApiKey,]);$res = json_decode(curl_exec($ch), true);
import requestsLWS_API_KEY = "…"res = requests.get(    "https://panelkvm.lwspanel.com/api/v1/servers",    headers={        "Authorization": "Bearer " + LWS_API_KEY,    },)print(res.json())
const LWS_API_KEY = "…";const res = await fetch("https://panelkvm.lwspanel.com/api/v1/servers", {  method: "GET",  headers: {    "Authorization": "Bearer " + LWS_API_KEY,  },});const data = await res.json();
lwsApiKey := "…"req, _ := http.NewRequest("GET",    "https://panelkvm.lwspanel.com/api/v1/servers", nil)req.Header.Set("Authorization", "Bearer "+lwsApiKey)resp, err := http.DefaultClient.Do(req)