REST API

Wo im Portal: API-Referenz unter https://<your-domain>/apidoc (öffentlich) und API-Schlüssel unter /api-keys. Wo im Admin-Bereich: Customers › API keys (/customers/apikeys) listet die von Kunden erstellten Schlüssel auf.

Funktion

Jede Aktion, die ein Kunde im Portal ausführen kann — VMs auflisten und steuern, Rechnungen lesen, SSH-Schlüssel, Kubernetes, Speicher sowie Support-Tickets verwalten —, ist über eine versionierte REST API unter https://<your-domain>/v1/ verfügbar. Kunden rufen sie aus Skripten und CI mit einem begrenzten API key auf. Dieselbe API speist das cmp Befehlszeilentool und den MCP server, und die Referenz wird aus der laufenden Installation generiert, sodass sie immer genau die Funktionen auflistet, die Sie eingeschaltet haben.

Anforderungen

Komponente	Anforderung
Öffentliche HTTPS-Adresse	Die API wird auf Ihrer Hauptdomain (und auf der eigenen Domain jedes Resellers) bereitgestellt.
Ein API-Schlüssel	Vom Kunden im Portal erstellt; siehe API keys.
Abhängigkeiten	Keine. Endpunkte eines Moduls, das Sie nicht aktiviert haben (zum Beispiel Kubernetes oder Object Storage), werden vor der Referenz verborgen und abgelehnt.

Infrastruktur vorbereiten

Nichts zu installieren. Wenn ein Reverse-Proxy vor NexCMP sitzt, leiten Sie /v1/, /mcp, /cli/ und /apidoc an das Panel weiter (die Nginx-Konfiguration des Installateurs tut dies bereits).

In NexCMP verbinden

Die interaktive Referenz

Öffnen Sie https://cloud.example.com/apidoc (ersetzen Sie den Host durch Ihre Domain; Kunden eines Resellers sehen die Referenz auf der Domain des Resellers mit dessen Namen). Sie bietet Endpunkt-Dokumentation mit Anfrage- und Antwortbeispielen in curl, der cmp CLI, JavaScript, Python und Go, ein Suchfeld (Strg oder Cmd + K) sowie ein Try it-Panel. Try it sendet Anfragen nur an dieselbe Website mit einem Schlüssel, den der Besucher einfügt (wird in der Browsersitzung gespeichert); es ist standardmäßig schreibgeschützt, und Schreib- oder kostenpflichtige Aufrufe erfordern einen zusätzlichen Schalter und eine Bestätigung.

Downloads und maschinenlesbare Dokumente

Alle sind öffentlich, benötigen keinen Schlüssel und werden pro Website generiert:

URL	Inhalt
`/apidoc`	Interaktive Referenz.
`/v1/public/openapi.json`	OpenAPI 3.1-Dokument.
`/v1/public/openapi.yaml`	Ebenso, YAML.
`/v1/public/postman.json`	Postman-Collection.
`/v1/public/insomnia.json`	Insomnia-Export.
`/v1/public/api.md`	Die Referenz als eine Markdown-Datei.
`/v1/public/api-catalog`	Light JSON: Marke, Basis-URL, Schlüsselpräfix, jeder Scope und jeder Endpunkt mit Methode, Pfad, Scope und Angabe, ob eine `Idempotency-Key` erforderlich ist.

bash

curl -s https://cloud.example.com/v1/public/api-catalog | python3 -m json.tool | head -40
curl -sO https://cloud.example.com/v1/public/openapi.yaml

Wählen Sie in Postman Import › Link und fügen Sie https://cloud.example.com/v1/public/postman.json ein. Die Referenzseite bietet zudem einteilige API-Clients für JavaScript und Python.

Authentifizierung

Senden Sie den Schlüssel im Header Authorization:

bash

curl -s https://cloud.example.com/v1/billing/wallet \
  -H "Authorization: Bearer vk_XXXX"

Kundenschlüssel beginnen mit vk_. Schlüssel sind an die Website gebunden: Ein auf cloud.example.com erstellter Schlüssel funktioniert auf einer Reseller-Domain nicht.
Browser-Session-Token (pt_...) sind nur für das Portal bestimmt; verwenden Sie für die Automatisierung einen Schlüssel.
Die Scopes des Schlüssels bestimmen, welche Aufrufe er tätigen darf; ein fehlender Scope führt zu HTTP 403 scope_required. Siehe API keys.
Überprüfen Sie einen Schlüssel mit GET /v1/apikeys/self: Dies gibt den Namen, die Scopes, das Ablaufdatum des aufrufenden Schlüssels sowie das verbleibende Kontingent des Rate-Limits zurück (jeder Schlüssel kann dies aufrufen).

Beispiele

bash

# List virtual machines
curl -s "https://cloud.example.com/v1/vm?page=1" -H "Authorization: Bearer vk_XXXX"

# Start one (needs vm:write)
curl -s -X POST https://cloud.example.com/v1/vm/3f2a1c9e-0000-4000-8000-000000000000/start \
  -H "Authorization: Bearer vk_XXXX"

# Create a VM (paid: needs vm:create and an Idempotency-Key)
curl -s -X POST https://cloud.example.com/v1/vm \
  -H "Authorization: Bearer vk_XXXX" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @vm.json

Entnehmen Sie die genauen Anfragefelder jeder Operation aus /apidoc.

Fehler

Jeder Fehler ist JSON mit einem stabilen code und einer menschenlesbaren message:

json

{"error": {"code": "scope_required", "message": "Key lacks scope vm:write"}}

HTTP	Typischer `code`	Bedeutung
401	`unauthenticated`, `key_invalid`, `key_revoked`, `key_expired`, `key_ip_denied`, `site_mismatch`, `api_keys_disabled`	Fehlender oder unbekannter Schlüssel, widerrufen, abgelaufen, Aufrufer-IP außerhalb der Erlaubnisliste des Schlüssels, ein Schlüssel von einer anderen Website oder deaktivierte API-Schlüssel.
403	`scope_required`, `endpoint_not_public`, `account_blocked`, `quota_exceeded`, `impersonate_forbidden`	Dem Schlüssel fehlt der Scope; der Endpunkt ist für Schlüssel nicht verfügbar; das Konto ist gesperrt; ein quota wurde erreicht; Aktion in einer übernommenen Session nicht zulässig.
404	`not_found`	Nicht gefunden — wird auch für Ressourcen zurückgegeben, die jemand anderem gehören.
422	`invalid_argument`	Validierungsfehler (Feld in der Antwort benannt).
429	`rate_limited`	Zu viele Anfragen; warten auf `Retry-After`.
503	`maintenance`	Wartungsmodus ist aktiv: Lesevorgänge funktionieren, Schreibvorgänge werden abgelehnt.

Rate-Limits

Limit	Standard
Pro Schlüssel	120 Anfragen pro Minute
Pro Konto (alle Schlüssel zusammen)	300 Anfragen pro Minute

Jede Antwort enthält X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset; ein Status 429 fügt Retry-After hinzu.

Idempotenz

Befehle, die Geld kosten oder nicht wiederholt werden können (Erstellen, Tarif wechseln, Kaufen, Löschen ...), erfordern einen Idempotency-Key-Header (beliebiger String bis zu 200 Zeichen; eine UUID eignet sich gut). Senden Sie denselben Schlüssel nach einer Zeitüberschreitung erneut, und der Server gibt das ursprüngliche Ergebnis zurück (mit Idempotency-Replayed: 1), anstatt die Operation zu wiederholen. Die Wiederverwendung eines Schlüssels für einen anderen Befehl ergibt 422; eine Anfrage, die noch verarbeitet wird, ergibt 409/Retry-After. Ohne den Header wird ein kostenpflichtiger Aufruf abgelehnt.

Verifizierung

Erstellen Sie im Portal einen Schlüssel mit dem Scope vm:read (API keys › Create key).

Führen Sie Folgendes aus:

bash

curl -i https://cloud.example.com/v1/apikeys/self -H "Authorization: Bearer vk_XXXX"

Sie erhalten HTTP 200 und die Rate-Limit-Header.

curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX" listet die VMs des Kontos auf. Im Portal zeigen die Spalte Last used des Schlüssels und das Key usage log die Aufrufe an.

Limits & Hinweise

Niemals für einen Schlüssel verfügbar: Guthaben aufladen, abheben, Karten oder automatisches Aufladen ändern, Passwort, E-Mail oder 2FA ändern, Konto löschen, andere Schlüssel erstellen, bearbeiten oder widerrufen. Dafür ist eine angemeldete Browsersession erforderlich.
Ausgeblendete Module: Die Referenz und das OpenAPI-Dokument listen nur Funktionen auf, die auf dieser Website aktiviert sind.
Antwortgröße und Paginierung: Listenendpunkte sind paginiert (page, per_page); lesen Sie das OpenAPI-Dokument für jeden Endpunkt.
Zeit und Geld: Beträge sind in USD-Cents angegeben, sofern der Feldname nichts anderes besagt.
Admin-API: Die Admin-Konsole verfügt über eine eigene Seite System › Admin › API und Administrator-Schlüssel (ofw_...) für die Administration; diese sind von der hier beschriebenen Kunden-API getrennt.
Versionierung: Das Pfadpräfix /v1 ist stabil; Antworten können neue Felder hinzugefügt werden.

Fehlerbehebung

Symptom	Ursache	Behebung
401 bei neuem Schlüssel	Schlüssel von einer anderen Domain, abgelaufen oder mit Leerzeichen eingegeben	Erstellen Sie den Schlüssel auf der aufgerufenen Domain; prüfen Sie den `Authorization: Bearer vk_...`-Header.
403 `scope_required`	Fehlender Scope	Bearbeiten Sie den Schlüssel im Portal und fügen Sie den Scope hinzu.
401 `key_ip_denied` oder `site_mismatch`	Schlüssel auf andere IPs beschränkt („erlaubte IPs“) oder auf einer anderen Domain erstellt	Fügen Sie die IP Ihres Servers zu den erlaubten IPs des Schlüssels hinzu oder rufen Sie die Domain auf, auf der der Schlüssel erstellt wurde.
404 bei einer existierenden VM	Die VM gehört zu einem anderen Account	Verwenden Sie einen Schlüssel des Eigentümers.
400/422 mit der Bitte um `Idempotency-Key`	Kostenpflichtiger Vorgang ohne den Header	Fügen Sie `Idempotency-Key: <uuid>` hinzu.
429	Limit überschritten	Warten Sie ab; verwenden Sie `Retry-After`.
`/apidoc` zeigt weniger als erwartet	Modul ausgeschaltet	Aktivieren Sie das Modul unter License & updates.

REST API ​

Funktion ​

Anforderungen ​

Infrastruktur vorbereiten ​

In NexCMP verbinden ​

Die interaktive Referenz ​

Downloads und maschinenlesbare Dokumente ​

Authentifizierung ​

Beispiele ​

Fehler ​

Rate-Limits ​

Idempotenz ​

Verifizierung ​

Limits & Hinweise ​

Fehlerbehebung ​

REST API

Funktion

Anforderungen

Infrastruktur vorbereiten

In NexCMP verbinden

Die interaktive Referenz

Downloads und maschinenlesbare Dokumente

Authentifizierung

Beispiele

Fehler

Rate-Limits

Idempotenz

Verifizierung

Limits & Hinweise

Fehlerbehebung