Alle Endpoints liefern application/json. Fehler folgen RFC 7807 (Problem+JSON). Antwort enthält stets den Header X-Request-Id zur Korrelation mit dem serverseitigen Audit-Log.
| Method | Path | Scope | Zweck |
|---|---|---|---|
| GET | /v1/health | public | Health-Check ohne Auth. |
| GET | /v1/me | any | Eigene Account-Info + Key-Metadaten. |
| GET | /v1/products | read:products | Liste aller öffentlich gelisteten Produkte mit Preisen. |
| GET | /v1/products/{id} | read:products | Produkt-Details inkl. Konfigurations-Optionen. |
| POST | /v1/orders | write:orders | Neue Bestellung. Idempotency-Key Pflicht. |
| GET | /v1/orders/{id} | read:orders | Status einer eigenen Bestellung. |
| GET | /v1/services | read:services | Liste der eigenen Services (paginiert). |
| GET | /v1/services/{id} | read:services | Details eines eigenen Service. |
| GET | /v1/services/{id}/credentials | read:credentials | Zugangsdaten (separater Scope, audit-geloggt). |
| POST | /v1/services/{id}/actions | write:services | Service-Aktion: start, stop, reboot, cancel (zum Laufzeitende), cancel_revoke. |
| GET | /v1/billing/balance | read:billing | Guthaben. |
| GET | /v1/billing/invoices | read:billing | Liste Ihrer Rechnungen (paginiert). |
| GET | /v1/billing/invoices/{id}/pdf | read:billing | Rechnungs-PDF. |
| GET | /v1/webhooks | read:webhooks | Aktuelle Webhook-URL. |
| PUT | /v1/webhooks | write:webhooks | Webhook-URL setzen oder entfernen. |
Idempotenz
POST /v1/orders und POST /v1/services/{id}/actions verlangen einen Idempotency-Key-Header (1 bis 80 Zeichen aus [A-Za-z0-9_.-]). Der Key ist an Methode, Pfad und Body gebunden. Wiederholen Sie dieselbe Anfrage mit demselben Key innerhalb einer Stunde, erhalten Sie die gespeicherte Antwort; danach kommt 410 mit reason replay_stale, dann bitte einen neuen Key senden. Derselbe Key mit anderem Body oder auf einem anderen Endpoint wird mit 409 idempotency_conflict abgelehnt.
Rate-Limits
Standardmäßig 60 Anfragen pro Minute (plus 20 Burst) und 5.000 pro Tag pro Key, 120 pro Minute pro Konto über alle Keys und 600 pro Minute pro Quell-IP. Bei Überschreitung folgt HTTP 429 mit dem Header Retry-After. Die Antwort-Header X-RateLimit-Remaining und X-RateLimit-Reset zeigen den Stand des Key-Limits.
