API Referenz
Verwenden Sie API-Operationen und interpretieren Sie deren Ergebnisse
Lesen Sie die verfügbaren Endpunkte, Idempotenzregeln, Antworten auf Warteschlangenaktionen und aktuellen Limits zur Betriebsverfolgung.
Auf dieser Seite
Bevor Sie beginnen
- Eine gültige Sitzung und für geschützte Änderungen deren CSRF-Token.
- Kennungen aus dem aktuellen Katalog oder authentifizierten API-Antworten.
- Ein eindeutiger Idempotency-Key für jede Bestellung, Auszahlung oder Hardware-Aktion.
Lesen Sie das Konto, bevor Sie es ändern
Verwenden Sie die Lese-Endpunkte, um Konto, Guthaben und Zielressource zu bestätigen. GET /api/v1/me gibt Benutzername, balanceUsd und das csrfToken der Sitzung zurück. Ressourcenkennungen sind kontospezifisch; verwenden Sie die für das aktuelle Konto zurückgegebene Server- oder Netzkennung, anstatt einen Wert aus einer anderen Umgebung zu kopieren.
Das aktuelle API ist eine kompakte Kontoschnittstelle, keine vollständige asynchrone Job-Plattform. Speichern Sie Referenzen erfolgreicher Schreibvorgänge in Ihren eigenen Aufzeichnungen. Es gibt keinen Endpunkt, um jede Bestellung aufzulisten, eine bestimmte geplante Aktion zu prüfen oder den neuesten Überprüfungsstatus einer Auszahlung abzurufen.
| Endpunkt lesen | Zurückgegebene Daten |
|---|---|
| GET /api/v1/ledger | Die neuesten 100-Ledger-Einträge, neueste zuerst; kein Paginierungsvertrag. |
| GET /api/v1/servers | Nicht beendete Server, Status, Region, paidThrough, graceUntil und autoRenew. |
| GET /api/v1/network | Zugewiesene Adressen, Präfixlängen, PTR-Werte und zugehörige Server-IDs. |
| GET /api/health | Grundlegende Service- und Katalogzahlen; keine Garantie für Konto- oder physische Servergesundheit. |
Verwenden Sie den passenden Änderungsendpunkt
Unterstützte Serveraktionen sind Neustart, power_off, Neuinstallation, mount_iso, KVM und rotate_root_password. Eine benutzerdefinierte ISO-URL muss öffentliches HTTPS ohne eingebettete Anmeldeinformationen verwenden. Die Bestelllaufzeit ist wöchentlich oder monatlich und entspricht sieben oder dreißig Tagen. Preis, Rabatte, Guthaben und Kapazität werden vom Dienst geprüft; senden Sie keinen clientseitig berechneten Preis als maßgeblich.
| Endpunkt | Anforderungsfelder und Ergebnis |
|---|---|
| POST /api/v1/orders | configId, regionId, osId, Laufzeit, Menge; optional sshPublicKey. Gibt Bestell-ID und ACCEPTED zurück. |
| POST /api/v1/deposit-addresses | Asset. Gibt Adresse, Asset, Netzwerk, erforderliche Bestätigungen und Modus zurück oder einen Fehler 'Abrechnung nicht verfügbar'. |
| POST /api/v1/withdrawals | asset, destination, usd. Gibt id und PENDING_REVIEW zurück; Guthaben wird gehalten. |
| POST /api/v1/servers/{id}/actions | Aktion; isoUrl für mount_iso. Gibt Aktions-ID und QUEUED zurück. |
| PUT /api/v1/servers/{id}/ddos | Modus: BASELINE oder ADVANCED. Gibt QUEUED oder UNCHANGED und quoteRequired zurück. |
| PUT /api/v1/network/{id}/rdns | ptr oder ein leerer Wert, um ihn zu löschen. Gibt den gespeicherten PTR-Wert zurück. |
Machen Sie Wiederholungsversuche bewusst
Bestellungen, Auszahlungen, Serveraktionen und DDoS-Anforderungen erfordern einen Idempotenzschlüssel. Verwenden Sie 8–100 Buchstaben, Zahlen, Bindestriche oder Unterstriche und weisen Sie für jede beabsichtigte Operation einen neuen Schlüssel zu. Bewahren Sie den ursprünglichen Schlüssel, die Ressource und die Nutzlast vor dem Senden auf, damit eine unklare Antwort untersucht werden kann.
Bestellungen können das vorhandene Ergebnis für denselben Schlüssel und dieselbe normalisierte Anfrage wiedergeben; geänderte Bestelldetails führen zu einem Konflikt. Serveraktions-Wiedergaben geben die vorhandene Aktion zurück, wenn sie kompatibel ist. Halten Sie Aktionsschlüssel über alle Server im Konto hinweg eindeutig. Auszahlungen melden einen Konflikt, wenn sie bereits aufgezeichnet wurden, anstatt die ursprüngliche Anfrage als Erfolg zurückzugeben.
POST /api/v1/servers/{serverId}/actions HTTP/1.1
Content-Type: application/json
x-csrf-token: <current-session-token>
Idempotency-Key: <unique-operation-key>
Cookie: <current-session-cookies>
{"action":"reboot"}Distinguish acceptance from completion
Eine 202 QUEUED-Antwort bestätigt, dass eine Hardware-Anfrage erfasst wurde. Sie enthält keine funktionierende KVM-URL, kein Ersatz-Root-Passwort und keinen Nachweis, dass die Maschine neu gestartet wurde. Ebenso bedeutet ACCEPTED, dass eine Bestellung in die Bereitstellung geht; PENDING_REVIEW bedeutet, dass eine Auszahlung auf die Prüfung durch einen Operator wartet. Bewahren Sie die zurückgegebene Kennung auf, wenn Sie nach der Ausführung fragen.
In dieser Version gibt es keine Route zur Abfrage des Aktionsstatus. Lesen Sie die Server- oder Netzwerkdaten erneut, wo relevant, und holen Sie die Operatorbestätigung für physische Effekte ein. Ein gespeicherter PTR oder eine DDoS-Präferenz allein ist keine Messung des öffentlichen DNS oder des Live-Netzwerkschutzes.
Auf Ausfälle reagieren, ohne Arbeit zu duplizieren
- 400-Validierungsfehler: Korrigieren Sie die dokumentierten Felder vor der erneuten Übermittlung.
- 401 oder 403: Sitzungsauthentifizierung oder CSRF-Verifizierung vor dem erneuten Versuch reparieren.
- 404: Überprüfen Sie, ob die Ressourcenkennung zum angemeldeten Konto gehört.
- 409: Prüfen Sie den Fehlercode; unzureichendes Guthaben, erschöpfte Kapazität und Idempotenzkonflikte erfordern unterschiedliche Reaktionen.
- 502 oder 503 bei Einzahlungen: Es wurde keine verwendbare neue Adresse zurückgegeben; initiieren Sie keinen Transfer.
- Zeitüberschreitung oder unlesbare Antwort: Überprüfen Sie verfügbare Kontodatensätze und bewahren Sie die ursprünglichen Anforderungsdetails auf. Erstellen Sie nicht blind einen neuen Operationsschlüssel.