API-Dokumentation

Anfragen senden

Anfrageformat

Alle Anfragen verwenden Standard-HTTP-Methoden. Derzeit unterstützt die API GET zum Lesen von Daten. Schreiboperationen werden in zukünftigen Versionen hinzugefügt.

Füge jeder Anfrage die folgenden Header hinzu:

Authorization: Bearer DEIN_API_SCHLÜSSEL
Accept: application/json

für Endpunkte, die einen Anfrage-Body akzeptieren (zukünftige POST/PUT/PATCH), Füge außerdem hinzu:

Content-Type: application/json

Antwortformat

Alle Antworten liefern JSON mit einer konsistenten Struktur.

Erfolgreiche Antworten verpacken Daten in einem data-Feld:

{
  "data": {
    "id": "abc123",
    "name": "mein-server",
    "status": "RUNNING"
  }
}

Listenantworten geben ein Array innerhalb von data zurück:

{
  "data": [
    { "id": "abc123", "name": "server-1" },
    { "id": "def456", "name": "server-2" }
  ]
}

Der Ping-Endpunkt ist eine Ausnahme — er gibt ein flaches Objekt ohne den data-Wrapper zurück.

Fehlerantworten

Fehler geben ein JSON-Objekt mit den Feldern error, code und status zurück:

{
  "error": "VPS not found",
  "code": "NOT_FOUND",
  "status": 404
}

Häufige Fehlercodes

Status Code Beschreibung
400 BAD_REQUEST Ungültige Anfrageparameter
400 INVALID_ID Die Ressourcen-ID im URL-Pfad hat ein ungültiges Format
401 UNAUTHORIZED Fehlender oder ungültiger API-Schlüssel
403 INSUFFICIENT_SCOPE API-Schlüssel hat nicht die erforderlichen Berechtigungen
404 NOT_FOUND Ressource existiert nicht oder ist nicht zugänglich
429 RATE_LIMITED Rate-Limit überschritten
500 INTERNAL_ERROR Unerwarteter Serverfehler

Anfrage-ID

Jede Antwort enthält einen X-Request-Id-Header. Du kannst auch deine eigene ID senden:

X-Request-Id: meine-id-123

Falls nicht angegeben, generiert der Server automatisch eine. Gib Anfrage-IDs an den Support weiter, um Probleme nachzuverfolgen.

Rate-Limit-Header

Jede Antwort enthält Informationen zum Rate-Limit:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1711540800

Weitere Details findest du auf der Seite Autorisierung.

Nur HTTPS

Alle API-Anfragen müssen HTTPS verwenden. HTTP-Anfragen werden umgeleitet.

Basis-URL

https://hosting.site.quest/api/v1