Per iniziare

Introduzione

L'API Panel KVM consente di gestire in modo programmatico i VPS KVM del Suo account LWS: inventario, monitoraggio, alimentazione, reinstallazione, snapshot, backup, firewall, rete e chiavi SSH. Offre le stesse funzioni del pannello clienti KVM, per i Suoi script, la Sua integrazione continua o il Suo monitoraggio.

Avvio rapido

1. Crei la Sua chiave API. Nel pannello KVM, apra la pagina API / MCP, riservata all'account principale. Indichi l'indirizzo IP da cui partiranno le Sue chiamate, attivi l'accesso, generi la chiave, quindi scelga i VPS che potrà gestire: tutti o una selezione. Una chiave che non copre ancora alcun VPS funziona, ma il suo elenco di VPS è vuoto. La chiave viene mostrata per intero una sola volta: la copi subito.

2. La salvi in una variabile d'ambiente, come fanno tutti gli esempi di questa documentazione:

export LWS_API_KEY="lws_live_sk_7Yc2Kp9RtNwQ4mZ8Bx3Vf1Hd6Ls0AjE2"

3. Verifichi che funzioni:

curl https://panelkvm.lwspanel.com/api/v1/me \
  -H "Authorization: Bearer $LWS_API_KEY"

La risposta indica l'account, il livello di permessi della chiave e il numero di VPS che copre.

4. Elenchi i Suoi VPS:

curl https://panelkvm.lwspanel.com/api/v1/servers \
  -H "Authorization: Bearer $LWS_API_KEY"

Ogni VPS è identificato dal suo vmid, che riutilizzerà in tutte le altre chiamate.

5. Avvii un'azione e ne segua l'avanzamento. Riavvii un VPS:

curl -X POST https://panelkvm.lwspanel.com/api/v1/servers/116807/power \
  -H "Authorization: Bearer $LWS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "reboot"}'

La risposta contiene un task ("id": "tsk_000002e1"). Lo interroghi finché il suo stato non è succeeded:

curl https://panelkvm.lwspanel.com/api/v1/tasks/tsk_000002e1 \
  -H "Authorization: Bearer $LWS_API_KEY"

Autenticazione

Ogni richiesta trasmette la chiave nell'intestazione Authorization, secondo lo schema Bearer. Non la inserisca mai in un URL: i log di accesso conservano gli indirizzi.

La chiave si configura dalla pagina API / MCP del pannello:

• Indirizzi autorizzati (obbligatorio): IPv4, IPv6 o intervalli CIDR. L'accesso non può essere attivato senza almeno un indirizzo. Una chiamata proveniente da un altro indirizzo viene rifiutata (403 ip_not_allowed).
• Attivazione: un interruttore disattiva l'accesso senza eliminare la chiave (401 access_disabled).
• Rigenerazione: una nuova chiave invalida immediatamente quella precedente e il titolare dell'account ne viene informato via e-mail.

Permessi e ambito

Ogni chiave riceve un livello di permessi:

Il livello richiesto è indicato all'inizio di ogni operazione. Una chiamata che supera il livello concesso viene rifiutata (403 insufficient_scope) e la risposta indica il livello necessario in required_level.

Il livello si sceglie nella pagina API / MCP del pannello. Il passaggio al livello Completo deve essere confermato con un codice inviato via e-mail al titolare dell'account; il ritorno a un livello inferiore non lo richiede.

L'ambito della chiave copre tutti i VPS dell'account, compresi quelli acquistati in seguito, oppure una selezione di VPS. Un VPS fuori ambito risponde esattamente come un VPS inesistente (404 vm_not_found).

Richieste e risposte

• Gli scambi avvengono in JSON, con codifica UTF-8. I corpi delle richieste vanno inviati con Content-Type: application/json.
• Una risorsa viene restituita in data.
• Un elenco viene restituito in data, accompagnato da un blocco meta. Gli elenchi lunghi (VPS, task, registro attività) sono paginati con page (predefinito 1) e per_page (predefinito 25, al massimo 100); gli elenchi brevi vengono restituiti per intero.
• Le date seguono il formato ISO 8601 con fuso orario: 2027-03-14T00:00:00+01:00.
• I volumi sono espressi in byte, ad eccezione di min_memory_gb nel catalogo dei sistemi.
• Gli identificativi sono stringhe, vmid compreso: "116807". Solo account_id, in GET /me, è un numero.
• Ogni risposta include un'intestazione X-Request-Id. La comunichi al supporto LWS per qualsiasi segnalazione: consente di ritrovare la chiamata esatta.

{
  "data": [
    {
      "id": "tsk_000002e1",
      "status": "succeeded",
      "action": "server.reboot",
      "vmid": "116807",
      "description": "Demande de reboot du serveur VPS-116807",
      "created_at": "2026-08-20T14:31:02+02:00",
      "finished_at": "2026-08-20T14:31:40+02:00"
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 }
}

Operazioni asincrone

Le operazioni contrassegnate da [Differed] (avvio, reinstallazione, snapshot, backup, firewall…) non vengono eseguite durante la richiesta: vengono messe in coda e rispondono 202 Accepted con il task creato.

{
  "data": {
    "tasks": [
      {
        "id": "tsk_000002e1",
        "status": "pending",
        "action": "server.reboot",
        "vmid": "116807",
        "description": "Demande de reboot du serveur VPS-116807",
        "created_at": "2026-08-20T14:31:02+02:00",
        "finished_at": null
      }
    ]
  }
}

Segua poi il task con Consultare un task, a intervalli di qualche secondo, finché status non vale succeeded o failed. Interrogarlo più spesso non accelera nulla e consuma la Sua quota.

Su un VPS può essere eseguita una sola operazione dello stesso tipo alla volta: una seconda richiesta viene rifiutata (409 task_already_running) e la risposta indica il task in corso in task_id.

Anche un VPS bloccato dall'hypervisor rifiuta le scritture (409 server_locked). Il campo reason indica cosa fare: operation_in_progress, è in corso un'operazione, riprovi dopo il tempo indicato dall'intestazione Retry-After; suspended, il VPS è in ibernazione, lo avvii prima; support_notified, il blocco è anomalo, il team LWS è stato avvisato e sta intervenendo, è inutile riprovare a ripetizione.

Durante un intervento annunciato da LWS sul server host di un VPS (aggiornamento, riavvio…), se tale server non risponde più, le scritture su quel VPS e le letture che interrogano l'hypervisor vengono rifiutate (503 server_maintenance). Il campo maintenance della risposta ne precisa la natura e la fine prevista, e l'intestazione Retry-After il tempo consigliato prima di riprovare. L'inventario e la scheda del VPS continuano a rispondere, con status: maintenance.

Le altre scritture (immagini ISO, DNS inverso, password root, chiavi SSH, set di regole) sono immediate e restituiscono direttamente il loro risultato.

Errori

Gli errori vengono restituiti nel formato application/problem+json:

{
  "type": "https://docs.lws.fr/kvm/errors/vm-not-found",
  "title": "VPS introuvable",
  "status": 404,
  "code": "vm_not_found",
  "detail": "Aucun VPS 999999 sur ce compte.",
  "request_id": "3f9a1c07b2e45d18"
}

Basi la Sua gestione su code, che è stabile. detail è destinato a un essere umano e può cambiare. A seconda dell'errore, la risposta contiene anche errors (dettaglio per parametro), required_level, task_id, lock e reason, oppure retry_after.

Quote

Le chiamate sono limitate per account, su una finestra mobile di un'ora, secondo tre famiglie indipendenti:

Un'operazione pesante è soggetta a due limiti: quello del VPS interessato e quello dell'account. Il limite per VPS evita che uno stesso server venga sollecitato in loop, senza penalizzare gli account con molti VPS; il messaggio di rifiuto indica quale dei due limiti è stato raggiunto.

Per non sovraccaricare gli hypervisor, lo stato e le metriche istantanee di un VPS vengono memorizzati nella cache per 15 secondi, e la cronologia delle metriche da 1 minuto a 1 ora a seconda del periodo. Interrogare più spesso restituisce lo stesso valore e consuma quota senza alcun vantaggio.

Le risposte alle chiamate autenticate indicano lo stato della quota nelle intestazioni X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Anche una chiamata autenticata ma rifiutata (parametro non valido, livello insufficiente, conflitto…) consuma credito; una chiamata respinta in fase di autenticazione, diretta a un percorso inesistente o rifiutata per superamento della quota (429) non ne consuma. Una volta raggiunto il limite, l'API risponde 429 rate_limited: attenda il numero di secondi indicato dall'intestazione Retry-After prima di riprovare.