VPS API Schnellstart, API-Key erstellen und ersten Server anlegen

Schritt 2. Authentifizierung und erste Anfrage

Alle Anfragen gehen an die Basis-URL https://helpervps.com/api/v1 und tragen den Header Authorization: Bearer KEY. Rufen Sie als erste Anfrage Ihre Serverliste ab. Gibt es keine Server, kommt eine leere Liste [] zurück.

curl -s $HVP/servers -H "Authorization: Bearer $HVP_KEY"

Pro Konto sind bis zu 300 Anfragen pro Minute möglich, das Erstellen von Servern bis zu 10 pro 10 Minuten. Für wiederholte Statusabfragen genügen Abstände von einigen Sekunden. Alle Antworten sind JSON, bei Fehlern kommt ein Statuscode mit {"error": "code"} zurück.

Schritt 3. Tarif, Region und Image wählen

Alle Werte für die Servererstellung stammen aus dem Katalog. GET /catalog liefert in einem Aufruf die angebotenen Tarife (plans), Regionen (locations), Images (images) und Zusatzoptionen (addons). Mit jq filtern Sie bequem nur die benötigten Teile.

curl -s $HVP/catalog -H "Authorization: Bearer $HVP_KEY" | jq '.plans[] | {code, type, vcpu, ram_mb, disk_gb, monthly}'
curl -s $HVP/catalog -H "Authorization: Bearer $HVP_KEY" | jq '.locations, .images'

• Tarifcode: wie s1 oder s2, steht für Typ und Größe. type ist basic (Standard SSD), fast (Hochleistung NVMe), cpu (dedizierte CPU) oder mem (High Memory). monthly ist der Monatspreis in US-Dollar.
• Regionscode: Städtenamen wie frankfurt, singapore oder seoul.
• Image-Code: Betriebssysteme wie ubuntu-24-04, debian-13 oder almalinux-10 und Apps wie app-docker oder app-wordpress.
• Zusatzoptionen: Anteil für automatisches Backup, Größen und GB-Preis der Zusatzfestplatte und Preis des DDoS-Schutzes. Nicht angebotene Optionen kommen als null.

Fehlt jq, installieren Sie es unter Ubuntu mit apt install -y jq, auf dem Mac mit brew install jq. Es ist dieselbe Liste wie in der Oberfläche; die Unterschiede je Tarif sehen Sie bequem auf der Preisseite.

Schritt 4. Server erstellen

Senden Sie den Tarif, den Standort, das Image und den Namen als JSON an POST /servers. Bezahlen Sie die erste Laufzeit Ihres gewählten Tarifs, und die Servererstellung beginnt.

curl -s -X POST $HVP/servers \
  -H "Authorization: Bearer $HVP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan":"s2","location":"frankfurt","image":"ubuntu-24-04","label":"web-1"}'

Bei Erfolg kommt Statuscode 201 mit den Serverdaten zurück. id ist der Servercode im Format S-XXXX-XXXX-XXXX, den Sie in allen weiteren Anfragen verwenden. root_password ist einmalig in dieser Antwort enthalten, speichern Sie es sofort. Auf der Serverseite ist es zudem 7 Tage sichtbar.

• label: der Servername. Bis zu 40 Zeichen aus Buchstaben, Ziffern, Punkt und Bindestrich, andere Zeichen werden durch Bindestriche ersetzt.
• backups: bei true wird das automatische Backup aktiviert.
• extra_disk_gb: Größe des zusätzlichen NVMe-Block-Volumes. Geben Sie einen der Werte aus sizes_gb im Katalog an (50, 100, 250, 500, 1000).
• ddos_protection: bei true wird der DDoS-Schutz aktiviert.

Optionspreise werden zum Server-Monatspreis addiert, im Feld monthly der Antwort angezeigt und an jedem Abrechnungstag zum selben Betrag automatisch verlängert. Pro Konto sind bis zu 10 Server möglich.

Schritt 5. Status prüfen und verbinden

Ein neuer Server startet im Status creating, wechselt nach der Bereitstellung zu running, und die ipv4-Adresse wird befüllt. Die folgende Schleife prüft alle 10 Sekunden den Status und zeigt die IP, sobald running erreicht ist. Ersetzen Sie den Servercode durch den Ihres Servers.

ID=S-XXXX-XXXX-XXXX
until [ "$(curl -s $HVP/servers/$ID -H "Authorization: Bearer $HVP_KEY" | jq -r .state)" = "running" ]; do sleep 10; done
curl -s $HVP/servers/$ID -H "Authorization: Bearer $HVP_KEY" | jq -r .ipv4

Der Status ist einer von creating, running, stopped, rebooting, installing, suspended oder check. suspended bedeutet, dass der Server pausiert wurde, weil er am Abrechnungsdatum nicht verlängert wurde, und check bedeutet, dass wir das Ergebnis der Server-Einrichtung prüfen. Sobald die IP erscheint, verbinden Sie sich mit ssh root@IP. Wie Sie sich verbinden, steht in der Anleitung zum ersten Login.

Schritt 6. Strom, Verlängerung, Löschen

curl -s -X POST $HVP/servers/$ID/stop   -H "Authorization: Bearer $HVP_KEY"
curl -s -X POST $HVP/servers/$ID/start  -H "Authorization: Bearer $HVP_KEY"
curl -s -X POST $HVP/servers/$ID/reboot -H "Authorization: Bearer $HVP_KEY"
curl -s -X POST $HVP/servers/$ID/renew  -H "Authorization: Bearer $HVP_KEY"
curl -s -X DELETE $HVP/servers/$ID     -H "Authorization: Bearer $HVP_KEY"

• start: schaltet einen gestoppten (stopped) Server ein.
• stop, reboot: fährt einen laufenden (running) Server herunter oder startet ihn neu.
• renew: bezahlt sofort weitere 1, 3, 6 oder 12 Monate. Ein gesperrter Server wird mit dieser Anfrage ebenfalls wieder aktiviert.
• DELETE: löscht Server und Festplatte und liefert {"state": "deleted"}. Der Rest des bereits bezahlten Monats wird nicht erstattet.

Senden Sie einen im aktuellen Status unmöglichen Vorgang, kommt 409 wrong_state zurück, etwa bei start an einen bereits laufenden Server. Neuinstallation und neues root-Passwort erledigen Sie auf der Serverseite; die Schritte stehen in der Anleitung zur Neuinstallation.

Dieselben Schritte in Python

Als Python-Skript sieht derselbe Ablauf so aus. Genutzt wird die Bibliothek requests (pip install requests).

import os, time, requests

API = "https://helpervps.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['HVP_KEY']}"}

r = requests.post(f"{API}/servers", headers=H, json={
    "plan": "s2", "location": "frankfurt",
    "image": "ubuntu-24-04", "label": "web-1",
})
r.raise_for_status()
server = r.json()
print("id:", server["id"], "root password:", server["root_password"])

while True:
    s = requests.get(f"{API}/servers/{server['id']}", headers=H).json()
    if s["state"] == "running" and s["ipv4"]:
        print("ready:", s["ipv4"])
        break
    time.sleep(10)

Häufige Fehlercodes

• 401 unauthorized: Der Key fehlt oder ist falsch. Prüfen Sie, ob der Header die Form Authorization: Bearer hvp_... hat.
• 403 not_allowed: wird freigeschaltet, sobald Ihre erste Zahlung bestätigt ist.
• 400 bad_request: Feldname oder Wert ist falsch. Verwenden Sie Codes genau wie im Katalog.
• 402 not_enough_balance: Der Zahlungsbetrag liegt unter $25. Senden Sie erneut mit mindestens $25.
• 409 limit: Die maximale Anzahl an Servern für Ihr Konto ist erreicht.
• 409 not_created: Der Server konnte nicht erstellt werden, und die Gebühr geht auf Ihr Kontoguthaben.
• 202 checking: Wir prüfen das Ergebnis der Server-Einrichtung. Senden Sie dieselbe Anfrage nicht erneut; prüfen Sie Ihre Serverliste. Der Server wird fertiggestellt oder die Gebühr wird auf Ihr Kontoguthaben zurückgezahlt.
• 404 not_found: Servercode oder Adresse existiert in Ihrem Konto nicht.
• 409 wrong_state: Dieser Vorgang ist im aktuellen Status nicht möglich.
• 429 rate_limited: Das Anfragelimit pro Minute ist erreicht. Warten Sie kurz und senden Sie dann.

Alle Endpunkte, Antwortfelder und Beispiele finden Sie in der API-Dokumentation. Was Sie mit der API tun können und Einsatzbeispiele zeigt die Seite VPS API.