Erste Schritte

Einführung

Mit der API Panel KVM steuern Sie die KVM-VPS Ihres LWS-Kontos programmgesteuert: Inventar, Überwachung, Stromversorgung, Neuinstallation, Snapshots, Backups, Firewall, Netzwerk und SSH-Schlüssel. Sie bietet dieselben Funktionen wie das KVM-Kundenpanel – für Ihre Skripte, Ihre Continuous Integration oder Ihr Monitoring.

Schnellstart

1. Erstellen Sie Ihren API-Schlüssel. Öffnen Sie im KVM-Panel die Seite API / MCP, die dem Hauptkonto vorbehalten ist. Hinterlegen Sie die IP-Adresse, von der aus Ihre Aufrufe erfolgen, aktivieren Sie den Zugang, erzeugen Sie den Schlüssel und wählen Sie dann die VPS aus, die er steuern darf: alle oder eine Auswahl. Ein Schlüssel, der noch keinen VPS abdeckt, funktioniert zwar, seine VPS-Liste ist jedoch leer. Der Schlüssel wird nur ein einziges Mal vollständig angezeigt: Kopieren Sie ihn sofort.

2. Speichern Sie ihn in einer Umgebungsvariablen, wie es alle Beispiele dieser Dokumentation tun:

export LWS_API_KEY="lws_live_sk_7Yc2Kp9RtNwQ4mZ8Bx3Vf1Hd6Ls0AjE2"

3. Prüfen Sie, ob er funktioniert:

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

Die Antwort nennt das Konto, die Berechtigungsstufe des Schlüssels und die Anzahl der VPS, die er abdeckt.

4. Listen Sie Ihre VPS auf:

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

Jeder VPS wird dort durch seine vmid bezeichnet, die Sie in allen weiteren Aufrufen verwenden.

5. Starten Sie eine Aktion und verfolgen Sie sie. Starten Sie einen VPS neu:

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"}'

Die Antwort enthält eine Aufgabe ("id": "tsk_000002e1"). Fragen Sie sie ab, bis ihr Status succeeded lautet:

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

Authentifizierung

Jede Anfrage enthält den Schlüssel im Header Authorization nach dem Schema Bearer. Übermitteln Sie ihn niemals in einer URL: Zugriffsprotokolle speichern die Adressen.

Der Schlüssel wird auf der Seite API / MCP des Panels konfiguriert:

• Zugelassene Adressen (Pflicht): IPv4, IPv6 oder CIDR-Bereiche. Ohne mindestens eine Adresse lässt sich der Zugang nicht aktivieren. Ein Aufruf von einer anderen Adresse wird abgelehnt (403 ip_not_allowed).
• Aktivierung: Ein Schalter sperrt den Zugang, ohne den Schlüssel zu löschen (401 access_disabled).
• Neu erzeugen: Ein neuer Schlüssel macht den alten sofort ungültig, und der Kontoinhaber wird per E-Mail benachrichtigt.

Berechtigungen und Umfang

Jeder Schlüssel erhält eine Berechtigungsstufe:

Die erforderliche Stufe steht am Anfang jedes Vorgangs. Ein Aufruf oberhalb der gewährten Stufe wird abgelehnt (403 insufficient_scope), und die Antwort nennt die geforderte Stufe in required_level.

Die Stufe wird auf der Seite API / MCP des Panels gewählt. Der Wechsel auf die Stufe Vollständig muss mit einem Code bestätigt werden, der per E-Mail an den Kontoinhaber gesendet wird; die Rückkehr zu einer niedrigeren Stufe erfordert keine Bestätigung.

Der Umfang des Schlüssels umfasst entweder alle VPS des Kontos, einschließlich später gekaufter, oder eine Auswahl von VPS. Ein VPS außerhalb des Umfangs antwortet genau wie ein nicht existierender VPS (404 vm_not_found).

Anfragen und Antworten

• Der Austausch erfolgt in JSON mit UTF-8-Kodierung. Anfragekörper werden mit Content-Type: application/json gesendet.
• Eine Ressource wird unter data zurückgegeben.
• Eine Liste wird unter data zurückgegeben, begleitet von einem Block meta. Lange Listen (VPS, Aufgaben, Aktivitätsprotokoll) werden über page (Standard 1) und per_page (Standard 25, höchstens 100) paginiert; kurze Listen werden vollständig zurückgegeben.
• Datumsangaben folgen dem Format ISO 8601 mit Zeitzonenversatz: 2027-03-14T00:00:00+01:00.
• Größen werden in Bytes angegeben, mit Ausnahme von min_memory_gb im Systemkatalog.
• Bezeichner sind Zeichenketten, auch vmid: "116807". Nur account_id in GET /me ist eine Zahl.
• Jede Antwort enthält einen Header X-Request-Id. Geben Sie ihn bei jeder Meldung an den LWS-Support weiter: Damit lässt sich der genaue Aufruf wiederfinden.

{
  "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 }
}

Asynchrone Vorgänge

Die mit [Differed] gekennzeichneten Vorgänge (Start, Neuinstallation, Snapshot, Backup, Firewall …) werden nicht während der Anfrage ausgeführt: Sie werden in eine Warteschlange gestellt und antworten mit 202 Accepted und der erstellten Aufgabe.

{
  "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
      }
    ]
  }
}

Verfolgen Sie die Aufgabe anschließend mit Aufgabe abrufen alle paar Sekunden, bis status den Wert succeeded oder failed hat. Häufigere Abfragen beschleunigen nichts und verbrauchen Ihr Kontingent.

Auf einem VPS kann jeweils nur ein Vorgang desselben Typs gleichzeitig laufen: Eine zweite Anfrage wird abgelehnt (409 task_already_running), und die Antwort nennt die laufende Aufgabe in task_id.

Ein vom Hypervisor gesperrter VPS lehnt ebenfalls Schreibvorgänge ab (409 server_locked). Das Feld reason gibt an, was zu tun ist: operation_in_progress – ein Vorgang läuft, versuchen Sie es nach der im Header Retry-After genannten Wartezeit erneut; suspended – der VPS befindet sich im Ruhezustand, starten Sie ihn zuerst; support_notified – die Sperre ist ungewöhnlich, das LWS-Team ist informiert und kümmert sich darum, wiederholte Versuche sind zwecklos.

Wenn während eines von LWS angekündigten Eingriffs am Hostserver eines VPS (Update, Neustart …) dieser Server nicht mehr antwortet, werden Schreibvorgänge auf diesem VPS und Lesevorgänge, die den Hypervisor abfragen, abgelehnt (503 server_maintenance). Das Feld maintenance der Antwort beschreibt Art und voraussichtliches Ende des Eingriffs, der Header Retry-After die empfohlene Wartezeit vor einem erneuten Versuch. Das Inventar und die Detailansicht des VPS antworten weiterhin, mit status: maintenance.

Die übrigen Schreibvorgänge (ISO-Images, Reverse DNS, Root-Passwort, SSH-Schlüssel, Regelsätze) erfolgen sofort und liefern ihr Ergebnis direkt zurück.

Fehler

Fehler werden im Format application/problem+json zurückgegeben:

{
  "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"
}

Stützen Sie Ihre Verarbeitung auf code, das stabil ist. detail richtet sich an Menschen und kann sich ändern. Je nach Fehler enthält die Antwort außerdem errors (Details je Parameter), required_level, task_id, lock und reason oder retry_after.

Kontingente

Aufrufe sind pro Konto über ein gleitendes Zeitfenster von einer Stunde begrenzt, in drei voneinander unabhängigen Gruppen:

Ein aufwendiger Vorgang unterliegt zwei Obergrenzen: der des betroffenen VPS und der des Kontos. Die Obergrenze pro VPS verhindert, dass ein einzelner Server in einer Schleife beansprucht wird, ohne Konten mit vielen VPS zu benachteiligen; die Ablehnungsmeldung gibt an, welche der beiden Obergrenzen erreicht ist.

Um die Hypervisoren zu schonen, werden Zustand und Momentanwerte eines VPS 15 Sekunden zwischengespeichert, der Metrikverlauf je nach Zeitraum 1 Minute bis 1 Stunde. Häufigere Abfragen liefern denselben Wert und verbrauchen Kontingent ohne Nutzen.

Die Antworten auf authentifizierte Aufrufe zeigen den Stand des Kontingents in den Headern X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset. Auch ein authentifizierter, aber abgelehnter Aufruf (ungültiger Parameter, unzureichende Stufe, Konflikt …) verbraucht Kontingent; ein bei der Authentifizierung abgewiesener Aufruf, ein Aufruf einer nicht existierenden Route oder ein wegen Überschreitung abgelehnter Aufruf (429) verbraucht keines. Ist die Grenze erreicht, antwortet die API mit 429 rate_limited: Warten Sie die im Header Retry-After angegebene Anzahl Sekunden ab, bevor Sie es erneut versuchen.