REST-API-Übersicht

Die REST-API ist die HTTP-API hinter der Konsole: Die Konsole sendet ihre eigenen Anfragen an sie. Sie rufen sie mit Bearer-Anmeldedaten auf, senden und empfangen JSON und adressieren die meisten Ressourcen über das Projekt, zu dem sie gehören.

Basis-URLLink kopieren

Die API wird unter /api/v1 auf einem eigenen Host bereitgestellt, dem API-Host, nicht auf dem Host der Konsole:

https://<api-host>/api/v1

• <api-host>: der Hostname der API. Er ist nicht der Host der Konsole.

Jeder Pfad in dieser Dokumentation und in der API-Referenz ist relativ zu dieser Basis-URL. Die REST-Entsprechung im letzten Schritt des Erstellungsassistenten für Instanzen ist ein curl-Befehl mit demselben Pfad und Body. Er richtet sich an den Host der Konsole: Um die API aus Ihrem eigenen Code aufzurufen, verwenden Sie den API-Host.

Interaktiver API-ExplorerLink kopieren

Der API-Host stellt die API-Referenz auch als interaktive Seite bereit, von der aus Sie Anfragen im Browser senden können:

https://<api-host>/docs

Wählen Sie Authorize, geben Sie ein API-Token oder einen Dienstkontoschlüssel ein und verwenden Sie dann Try it out bei einer Operation. Die Anfragen gehen mit Ihren Anmeldedaten an den API-Host und wirken auf Ihre echten Ressourcen. Beginnen Sie daher mit Lesezugriffen oder mit einem Projekt, das Sie zum Testen verwenden. Die Seite behält die Anmeldedaten nur, bis Sie sie neu laden oder schließen. Das OpenAPI-Dokument hinter der Seite liegt unter https://<api-host>/openapi.json; verwenden Sie es, um einen Client zu generieren oder die API in ein API-Werkzeug zu importieren.

Die API-Referenz auf dieser Website beschreibt dieselben Operationen und sendet keine Anfragen.

BereicheLink kopieren

Die meisten Ressourcen gehören zu einem Projekt, und ihre Pfade beginnen mit /scopes/, gefolgt von der ID des Projekts:

/scopes/<project-id>/compute/instances

• <project-id>: die ID des Projekts, das die Ressourcen enthält.

Das Segment nach der Projekt-ID benennt den Dienst, z. B. compute, storage oder network. Einige Pfade liegen nicht unter einem Projekt, z. B. /operations/<operation-id>. Die vollständige Pfadstruktur und wie Sie die ID eines Projekts ermitteln, finden Sie unter Bereiche, URLs und Anfrageformat.

AuthentifizierungLink kopieren

Jede Anfrage enthält im Header Authorization Anmeldedaten: ein API-Token, das mit pc_live_ beginnt, oder einen Dienstkontoschlüssel, der mit sak_live_ beginnt. Das API-Gateway prüft bei jeder Anfrage die Anmeldedaten und, bei den Ressourcen eines Projekts, Ihren Zugriff auf dieses Projekt, bevor die Anfrage einen Dienst erreicht. Details finden Sie unter Mit API-Tokens authentifizieren.

Synchrone und asynchrone AnfragenLink kopieren

Lesezugriffe geben 200 OK mit dem Ergebnis zurück. Schreibzugriffe antworten auf eine von zwei Arten:

• Synchron. Die Änderung ist abgeschlossen, wenn die Antwort eintrifft: 200 OK oder 201 Created mit dem Ergebnis oder 204 No Content.
• Asynchron. Die Plattform nimmt die Anfrage an und führt die Arbeit anschließend in der Cloud aus. Die Antwort ist 202 Accepted. So funktionieren z. B. das Erstellen einer Instanz oder eines Volumes, das Löschen einer Instanz und das Starten oder Stoppen einer Instanz.

Die API-Referenz zeigt den Erfolgsstatus jedes Vorgangs.

Eine Antwort 202 Accepted hat einen von zwei Bodys:

Wenn der Vorgang in einer Antwort 202 Accepted bereits SUCCEEDED ist, ist die Arbeit abgeschlossen. Schreibzugriffe der Abrechnung, etwa das Erstellen eines Budgets oder einer Verpflichtung, antworten auf diese Weise, und ihre Vorgänge können danach nicht gelesen werden.

Ein Vorgang verfolgt eine asynchrone Anfrage. Lesen Sie ihn mit GET /operations/<operation-id>:

{
  "id": "3f2b8c1e9d4a4f6b8e2c7a1d5b9e0f42",
  "action": "compute.instance.stop",
  "state": "RUNNING",
  "resourceKind": "instance",
  "resourceId": "9c1d6e2a7b3f4c8d9e0a1b2c3d4e5f60",
  "resourceName": "web-01",
  "createdAt": "2026-10-08T09:30:00Z",
  "startedAt": "2026-10-08T09:30:01Z",
  "updatedAt": "2026-10-08T09:30:01Z"
}

SUCCEEDED, FAILED und CANCELLED sind endgültig. Um einen Vorgang abzubrechen, der noch nicht abgeschlossen ist, senden Sie POST /operations/<operation-id>/actions/cancel mit dem Header Idempotency-Key. Das Abbrechen eines bereits abgeschlossenen Vorgangs gibt 409 Conflict zurück.

Sie können einen Vorgang nur lesen, wenn Sie seine Ressource in ihrem Projekt lesen können; andernfalls antwortet die API mit 404 Not Found. Um ihn abzubrechen, benötigen Sie die Berechtigung, diese Ressource zu verwalten.

Zeitstempel in Antworten sind ISO-8601-Zeichenfolgen in UTC, wie im Beispiel.

Idempotente SchreibzugriffeLink kopieren

Senden Sie bei jedem Schreibzugriff den Header Idempotency-Key. Wenn das Netzwerk ausfällt und Sie nicht wissen, ob eine Anfrage angekommen ist, senden Sie sie mit demselben Schlüssel erneut: Die Plattform gibt das Ergebnis der ersten Anfrage zurück, statt die Änderung ein zweites Mal anzuwenden. Einige Vorgänge ignorieren den Schlüssel. Die Regeln und die Ausnahmen finden Sie unter Idempotente Anfragen. Mit einem API-Token oder einem Dienstkontoschlüssel wird eine Anfrage mit POST, die eine Ressource erstellt, ohne den Schlüssel abgelehnt: 400 Bad Request mit dem Code IDEMPOTENCY_KEY_REQUIRED. Bei anderen Schreibzugriffen ist der Schlüssel optional.

ParallelitätssteuerungLink kopieren

Viele Ressourcen geben beim Lesen einen Header ETag zurück. Um sicherzustellen, dass Sie die Version ändern, die Sie gelesen haben, senden Sie diesen Wert bei der Aktualisierung im Header If-Match. Wenn sich die Ressource inzwischen geändert hat, gibt die Aktualisierung 412 Precondition Failed zurück: Lesen Sie die Ressource erneut, und wiederholen Sie die Aktualisierung.

curl -X PATCH "https://<api-host>/api/v1/scopes/<project-id>/compute/instances/<instance-id>" \
  -H "Authorization: Bearer $PC_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'If-Match: <etag>' \
  -H "Content-Type: application/json" \
  -d '{"name": "web-02"}'

• <instance-id>: die ID der Instanz.
• <etag>: der genaue Wert des Headers ETag aus Ihrem letzten Lesezugriff auf die Instanz, z. B. W/"3a7bd3e2360a3d29eea436fcfb7e44c735d117c4".
• PC_TOKEN: eine Umgebungsvariable, die Ihr API-Token enthält.

Diese Aktualisierungen erfordern If-Match. Ohne den Header geben auch sie 412 Precondition Failed zurück:

• Aktualisieren einer Instanz, eines Volumes, eines Netzwerks, eines Subnetzes, eines Routers, einer Sicherheitsgruppe, einer Netzwerkschnittstelle oder eines Load Balancers.
• Aktualisieren oder Löschen eines Backup-Plans.

Senden Sie für ein Subnetz das ETag seines Netzwerks. Subnetze haben kein eigenes ETag, und eine Aktualisierung eines Subnetzes gibt das neue ETag des Netzwerks zurück.

Listen und PaginierungLink kopieren

Listenvorgänge geben die Elemente in data und den Paginierungsstatus in meta zurück. Details finden Sie unter Paginierung.

Fehler und RatenbegrenzungLink kopieren

Fehlerantworten der API haben eine gemeinsame JSON-Form mit einem maschinenlesbaren code, einer message und, wenn eine Wiederholung erfolgreich sein kann, "retryable": true. Wenn Sie Anfragen zu schnell senden, gibt die API 429 Too Many Requests mit einem Header Retry-After zurück. Jede Antwort auf eine Anfrage mit einem API-Token oder einem Dienstkontoschlüssel enthält die Header X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset; X-RateLimit-Reset ist die Anzahl der Sekunden, bis das Limit zurückgesetzt wird. Die Codes und ihre Behandlung finden Sie unter Fehler.

Anfrage-IDsLink kopieren

Jede Antwort enthält einen Header X-Request-Id. Wenn Sie selbst einen Header X-Request-Id senden, verwendet die API Ihren Wert; andernfalls erzeugt sie einen. Geben Sie die ID an, wenn Sie ein Problem mit einer Anfrage melden.

Versionierung und ÄnderungenLink kopieren

Innerhalb von v1 ändert sich die API nur abwärtskompatibel. Eine inkompatible Änderung wird mindestens 6 Monate im Voraus angekündigt, und die Antworten des betroffenen Vorgangs tragen die Header Deprecation und Sunset. Die Regeln finden Sie unter API-Versionierung und Abkündigung, die Änderungen im API-Änderungsprotokoll.

Zugehörige AufgabenLink kopieren

• Mit API-Tokens authentifizieren
• Bereiche, URLs und Anfrageformat
• Idempotente Anfragen
• API-Versionierung und Abkündigung
• API-Änderungsprotokoll
• API-Referenz