VPS mit REST-API und curl verwalten: Status, Power, Neuinstallation, Verlängerung

Einen Server über die API zu bestellen, kostet eine Anfrage. Das steht in Einen VPS in 4 API-Aufrufen bestellen. Diese Seite behandelt alles danach: die Routineaktionen, die Sie sonst im Dashboard anklicken würden, als curl-Befehle zum Einfügen in ein Skript.

Jeden Befehl unten haben wir vor der Veröffentlichung gegen unsere API ausgeführt; die Antworten sind gekürzte Kopien dessen, was zurückkam.

Vorbereitung

Zwei Variablen halten die Befehle kurz:

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

Der Token kommt aus POST /auth/register oder aus Settings → API tokens im Dashboard. Halten Sie ihn aus der Shell-History heraus, wenn andere die Maschine nutzen; ihn mit export EQVPS_TOKEN=$(cat ~/.eqvps_token) aus einer Datei zu lesen, genügt.

Ihre Server finden

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

Jeder Eintrag hat eine id wie 47HZ7YF. Das ist der Service-Code, den jeder andere Aufruf erwartet. Dann das vollständige Bild eines Servers:

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 sagt Ihnen, wie Sie sich einloggen. Bei einem Tarif mit eigener IPv4 ist der Port 22; bei einem NAT-Tarif ist es Ihr persönlicher weitergeleiteter Port. Dieser Aufruf liest nur, Abfragen in einer Schleife sind also unbedenklich.

Haben Sie ohne SSH-Schlüssel bestellt, wird das root-Passwort einmal angezeigt:

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

Solange der Server noch bootet, lautet die Antwort password_pending, und die einmalige Anzeige ist nicht verbraucht. Warten Sie eine halbe Minute und fragen Sie erneut.

Power: Start, Stopp, Neustart

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

action ist start, stop oder reboot. Ein Server, der noch nicht aktiv ist (wird noch erstellt oder wegen Nichtzahlung gesperrt), antwortet mit 409 Service is not active. Das ist kein Fehler in Ihrem Skript. Prüfen Sie zuerst status.

Metriken

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

CPU, Speicher, Netzwerk und Festplatte als Zeitreihe. timeframe ist hour (Standard), day, week oder month. Gut für einen Cronjob, der Sie benachrichtigt, wenn die Festplatte stetig voller wird. Die Traffic-Zähler für den aktuellen Abrechnungszeitraum stehen unter Geschwindigkeit und Traffic prüfen.

Server umbenennen

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

Der neue Name wird vom Guest-Agent im laufenden System gesetzt, unter Linux ohne Neustart. Ist der Server gestoppt oder haben Sie qemu-guest-agent entfernt, liefert der Aufruf 409 agent_unavailable, und nichts ändert sich.

OS neu installieren

Das löscht die Festplatte. Die API verlangt, dass Sie den aktuellen Hostnamen des Servers in confirm eintragen, damit ein Skript mit falscher Service-ID nicht die falsche Maschine löscht:

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 stammt aus der Liste available_os Ihres Tarifs in GET /products oder aus den Details des Servers selbst. Die Neuinstallation läuft im Hintergrund; fragen Sie GET /services/{id} ab, bis status wieder active ist.

Verlängerung und Guthaben

Server verlängern sich monatlich aus Ihrem Prepaid-Guthaben. So sehen Sie, was längere Laufzeiten für diesen Server kosten:

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

Um im Voraus zu zahlen, etwa drei Monate, mit einem Aufruf:

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

months ist 1, 3, 6 oder 12, und 12 wird zum Jahrespreis mit dessen Rabatt berechnet. Die Antwort enthält paid_from_balance: true und das neue Ablaufdatum. Deckt das Guthaben den Betrag nicht, wird nichts abgebucht: Sie erhalten paid_from_balance: false und stattdessen eine checkout_url für diese Rechnung. Ist das Guthaben aufgeladen, bezahlt POST $API/invoices/{invoice_id}/pay diese Rechnung aus dem Guthaben; reicht es immer noch nicht, kommt dieselbe Art checkout_url zurück, und nichts wird abgebucht. Guthaben prüfen und aufladen:

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

Die Antwort zur Aufladung enthält eine checkout_url. Das ist ein Krypto-Checkout: USDT, USDC oder ETH auf Base, Ethereum oder Polygon. Das Guthaben wird gutgeschrieben, sobald die Zahlung on-chain bestätigt ist. Das Bezahlen ist der eine Schritt, den ein Skript nicht für Sie erledigen kann, es sei denn, es hält eine Wallet.

Monero geht auch, aber nur als Guthabenaufladung mit manueller Prüfung: Sie senden XMR, reichen die Transaktions-ID ein, und wir schreiben es nach der Prüfung gut. Siehe Mit Monero bezahlen.

Kündigen und es sich anders überlegen

Die sichere Art der Kündigung lässt den Server bis zum Ende des bezahlten Zeitraums laufen und verlängert ihn einfach nicht:

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 ist Pflicht. Ein paar Worte genügen. Vor dem Datum umentschieden?

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

Es gibt auch "type": "immediate". Das löscht den Server samt Daten sofort, braucht "confirm": "<hostname>" und lässt sich nicht rückgängig machen. Wenn Sie es nicht wirklich so meinen, nehmen Sie end_of_period.

Den Token am Leben halten

Neue Tokens leben standardmäßig ein Jahr. Jede authentifizierte Antwort trägt einen Header X-Token-Expires-At, sodass ein Skript es früh bemerken kann. Den Token gegen einen frischen tauschen:

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

Der alte Token funktioniert sofort nicht mehr; speichern Sie den neuen also, bevor Sie irgendetwas anderes tun.

Fehler, die sich zu behandeln lohnen

Sie machen das lieber aus einem KI-Client statt aus einem Skript? Dieselben Aktionen gibt es als MCP-Tools — siehe Wie ein Agent seinen eigenen VPS über MCP betreibt und die API-Referenz. Noch kein Server? Tarif wählen.