Kunden-API
Alles, was du im Panel klicken kannst, geht auch per API – für Automatisierung, Terraform-Skripte oder deinen eigenen Reseller-Shop. REST mit JSON, Geld immer in Cent, Zeiten in ISO 8601.
Schnellstart
- Im Panel unter Konto › API-Schlüssel einen Schlüssel anlegen (nur Inhaber und Admins). Er wird nur einmal angezeigt.
- Jede Anfrage mit Authorization: Bearer zc_… an https://api.zwicky.cloud/v1 schicken.
- Für Bestellungen braucht der Schlüssel das Recht „lesen + schreiben“.
curl -H "Authorization: Bearer $ZWICKY_TOKEN" https://api.zwicky.cloud/v1/account
curl -X POST https://api.zwicky.cloud/v1/servers \
-H "Authorization: Bearer $ZWICKY_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"host_line":"de_epyc","plan_id":2,"os":"debian-13","name":"web-01","ssh_key_ids":[1]}'
# Antwort 202: {"data":{"id":17,"status":"provisioning",…,"root_password":"…"},"job":{"id":"…","status":"queued"}}
curl -H "Authorization: Bearer $ZWICKY_TOKEN" https://api.zwicky.cloud/v1/jobs/<job-id>
Endpunkte
Konto und Angebot
| GET | /account | Konto, Guthaben, Verfügungsrahmen, verfügbarer Betrag, Restlaufzeit in Stunden |
| GET | /host-lines | Hostsysteme mit Grenzen, Preisen (Cent netto je Monat) und Vorlagen |
| GET | /os-images | Betriebssysteme (slug für Bestellung und Neuinstallation) |
SSH-Schlüssel
| GET | /ssh-keys | Alle Schlüssel |
| POST | /ssh-keys | Schlüssel hinzufügen: name, public_key |
| DELETE | /ssh-keys/{id} | Schlüssel entfernen |
Server
| GET | /servers | Alle Server (Seiten: ?page, ?per_page bis 100) |
| POST | /servers | Server bestellen – Idempotency-Key Pflicht, Antwort 202 mit job und einmaligem root_password |
| GET | /servers/{id} | Ein Server mit IPs, Stand und laufendem Auftrag |
| POST | /servers/{id}/actions/{action} | start, stop (hart), shutdown, reboot – Antwort 202 mit job |
| POST | /servers/{id}/reinstall | Neu installieren: os, ssh_key_ids – löscht alle Daten |
| DELETE | /servers/{id} | Server löschen (Abrechnung endet mit der laufenden Stunde) |
| GET | /jobs/{id} | Stand eines Auftrags: queued, running, done, failed |
Abrechnung
| GET | /transactions | Buchungen (Aufladungen, Verbrauch je Stunde, Erstattungen) |
| GET | /usage | Verbrauch je Server im Monat (?period=JJJJ-MM) |
| GET | /invoices | Monatsrechnungen |
| GET | /invoices/{id} | Eine Rechnung mit Positionen |
| GET | /invoices/{id}/xml | E-Rechnung als CII-XML (EN 16931) |
Server bestellen
Entweder eine Vorlage (plan_id aus /host-lines) oder freie Größe mit cores, ram_gb, disk_gb innerhalb der Grenzen des Hostsystems. Optional ipv4 (Anzahl, 1 inklusive) und ssh_key_ids. Der verfügbare Betrag (Guthaben + Verfügungsrahmen) muss für mindestens 24 Stunden reichen. Das Root-Passwort steht nur in dieser einen Antwort.
Aufträge
Anlegen, Steuern, Neuinstallation und Löschen laufen im Hintergrund. Die Antwort ist 202 Accepted mit einem job; dessen Stand fragst du unter /jobs/{id} ab, bis er done oder failed ist (z. B. alle 5 Sekunden). Je Server läuft immer nur ein Auftrag – sonst 409.
Idempotency-Key
Schick bei ändernden Anfragen eine eindeutige Kopfzeile Idempotency-Key (8–100 Zeichen, z. B. eine UUID) mit. Wiederholst du dieselbe Anfrage mit demselben Schlüssel – etwa nach einem Netzabbruch –, bekommst du 24 Stunden lang dieselbe Antwort (Kopfzeile Idempotent-Replayed: true), statt dass ein zweiter Server entsteht. Beim Bestellen ist er Pflicht. Derselbe Schlüssel mit anderem Inhalt ergibt 422.
Fehler
Fehler kommen als application/problem+json nach RFC 9457 mit type, title, status, detail und request_id (bei Eingabefehlern zusätzlich errors). Jede Antwort trägt X-Request-Id – nenn sie bei Support-Anfragen.
| 400 | Anfrage unvollständig, z. B. Idempotency-Key fehlt |
| 401 | Schlüssel fehlt, ungültig, abgelaufen oder widerrufen |
| 403 | IP nicht erlaubt, nur Lesezugriff oder Konto gesperrt |
| 404 | nicht gefunden (oder gehört nicht zu deinem Konto) |
| 409 | Aktion gerade nicht möglich, z. B. es läuft schon ein Auftrag |
| 422 | Eingaben ungültig oder Bestellung nicht möglich (Grenzen, Guthaben, Kapazität) |
| 429 | zu viele Anfragen – 120 je Minute und Schlüssel, siehe Retry-After |
| 500 | interner Fehler – bitte mit request_id melden |
Sicherheit
Schlüssel lassen sich auf Lesen beschränken, an IP-Adressen oder Netze binden und befristen. Wir speichern nur einen Prüfwert, nicht den Schlüssel selbst. Jede Aktion steht im Protokoll deines Kontos. Ein widerrufener Schlüssel funktioniert sofort nicht mehr.