# API-Referenz

Source : https://webgune.cloud/de-de/docs/reference-api · Mis à jour le 2026-10-27

# API-Referenz

Die Webgune-API ist eine REST-API in JSON. Es gibt zwei Oberflächen:

- `https://api.webgune.cloud/api/*` wird intern vom Dashboard verwendet, nicht versioniert.
- `https://api.webgune.cloud/api/v1/*` ist die **öffentliche Oberfläche**, stabil, für Integrationen von Drittanbietern gedacht (CI/CD, Skripte, Ihr eigenes Tooling). Verwenden Sie diese.

Die [interaktive Referenz](/developers/api-reference), generiert aus dem OpenAPI-Spec (`GET /api/v1/openapi.json`), listet jeden Endpunkt mit seinen genauen Anfrage- und Antwortschemas auf.

## Authentifizierung

Zwei Methoden, zur Wahl:

**API-Schlüssel**, empfohlen für ein Skript oder eine Integration eines Drittanbieters (Erstellung und Scopes: [API-Schlüssel](/docs/cles-api)):

```bash
curl https://api.webgune.cloud/api/v1/projects \
  -H "Authorization: Bearer wgk_xxxxxxxxxxxx"
```

**Session-Cookie** (vom Dashboard selbst verwendet):

```bash
POST /api/auth/login
Content-Type: application/json

{ "email": "sie@beispiel.com", "password": "..." }
```

Die Antwort setzt das Cookie `sid`; es muss bei jedem folgenden Aufruf übermittelt werden (`credentials: "include"` auf Fetch-Seite). Eine Session wird nicht durch Scopes eingeschränkt, weil sie Ihr angemeldetes Konto darstellt.

## Fehler

Jede Fehlerantwort folgt demselben Format:

```json
{ "error": "Lesbare Nachricht", "code": "optionaler_maschinen_code" }
```

Standard-HTTP-Codes: `400` ungültiger Payload, `401` fehlende/ungültige Authentifizierung, `403` unzureichender Scope oder unzureichende Rolle, `404` Ressource nicht gefunden oder nicht zugänglich (beides wird nicht unterschieden, um nicht die Existenz einer Ressource gegenüber jemandem zu offenbaren, der keinen Zugriff darauf hat), `409` Konflikt, `429` Ratenlimit überschritten.

## Ratenlimit

Jeder API-Schlüssel hat sein eigenes Limit (60 Anfragen/Minute standardmäßig, bei Erstellung konfigurierbar bis zu 6000). Jede Antwort trägt die Header:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1732549800
```

Ein Session-Cookie wird niemals durch diesen Mechanismus limitiert.

## Projekte

```text
GET    /api/v1/projects              Ihre Projekte auflisten (Eigentümer oder Mitglied)
POST   /api/v1/projects              ein Projekt erstellen
GET    /api/v1/projects/:id          Details eines Projekts (Dienste, Canvas)
PUT    /api/v1/projects/:id          umbenennen / Beschreibung ändern
DELETE /api/v1/projects/:id          ein Projekt löschen
```

```bash
curl -X POST https://api.webgune.cloud/api/v1/projects \
  -H "Authorization: Bearer wgk_xxxxxxxxxxxx" -H "Content-Type: application/json" \
  -d '{ "name": "mein-projekt" }'
```

Verwaltung von Mitgliedern, Canvas (Positionen/Verbindungen) und Domain-Weiterleitungen auf Projektebene: siehe die [interaktive Referenz](/developers/api-reference), noch nicht im generierten Spec abgedeckt.

## Dienste

```text
GET    /api/v1/services/project/:projectId   Dienste eines Projekts
GET    /api/v1/services/:id                  Details eines Dienstes (Live-K8s-Status)
POST   /api/v1/services                      einen Dienst erstellen (GitHub, Upload, Docker, Datenbank)
DELETE /api/v1/services/:id                  einen Dienst löschen
POST   /api/v1/services/:id/redeploy         neu deployen
GET    /api/v1/services/:id/logs             aktuelle Runtime-Logs
GET    /api/v1/services/:id/metrics          CPU / Speicher momentan
GET    /api/v1/services/:id/env              Umgebungsvariablen
PUT    /api/v1/services/:id/env              Variablen ersetzen (startet den Dienst neu)
PUT    /api/v1/services/:id/scale            Anzahl der Replikate festlegen
GET    /api/v1/services/:id/deployments      Deployment-Historie
POST   /api/v1/services/:id/deployments/:deploymentId/rollback   zu einem vorherigen Deployment zurückkehren
```

```bash
curl -X POST https://api.webgune.cloud/api/v1/services/svc_123/redeploy \
  -H "Authorization: Bearer wgk_xxxxxxxxxxxx"
```

Branch-Previews, Datenbank-Exposition, Volumes, benutzerdefinierte Ports, Autoscaling, Discord-Bots: bestehende Endpunkte, noch nicht im generierten OpenAPI-Spec. Siehe [Datenbanken](/docs/bases-de-donnees), [Autoscaling](/docs/autoscaling), [Deployments & Rollback](/docs/deploiements-rollback).

## Domains

```text
POST   /api/v1/domains/check              Verfügbarkeit einer Domain prüfen
GET    /api/v1/domains                    Ihre Domains auflisten
POST   /api/v1/domains/register           eine verfügbare Domain registrieren
GET    /api/v1/domains/:id                Details einer Domain
DELETE /api/v1/domains/:id                eine Domain löschen
GET    /api/v1/domains/:id/dns            DNS-Einträge auflisten
POST   /api/v1/domains/:id/dns            einen DNS-Eintrag hinzufügen
DELETE /api/v1/domains/:id/dns/:idx       einen DNS-Eintrag löschen
```

Nameserver, automatische Verlängerung, manuelle Verlängerung: siehe die [interaktive Referenz](/developers/api-reference).

## Abrechnung

```text
GET    /api/v1/billing/plans          verfügbare Pläne auflisten
GET    /api/v1/billing/subscription   aktives Abonnement (Konto, oder ?projectId= für ein dediziertes Projekt)
GET    /api/v1/billing/invoices       Ihre Rechnungen auflisten
```

Abonnement, Zahlung und Webhook bleiben interne Dashboard-Abläufe (Mollie), nicht als API-Operationen für Drittanbieter exponiert.

## Dashboard

```text
GET    /api/v1/dashboard/stats                aggregierte Statistiken (Dienste, CPU/Speicher vs. Plan-Limits)
GET    /api/v1/dashboard/deployment-history    Deployment-Historie, letzte 30 Tage
```

## API-Schlüssel

```text
GET    /api/v1/api-keys                     Ihre Schlüssel auflisten
POST   /api/v1/api-keys                     einen Schlüssel erstellen
DELETE /api/v1/api-keys/:id                 einen Schlüssel widerrufen
GET    /api/v1/api-keys/:id/audit-log       Audit-Protokoll (letzte 100 Anfragen)
```

Details zu Scopes, Ratenlimit und dem Header `X-Act-As-User-Id` (Reseller): siehe [API-Schlüssel](/docs/cles-api).

## Reseller

Vorbehalten Konten, die Eigentümer einer Organisation sind (`isOrgOwner`):

```text
GET    /api/v1/reseller/organization    meine Organisation
GET    /api/v1/reseller/sub-clients     meine Unterkunden auflisten
GET    /api/v1/reseller/overview        Übersicht (Zähler je Unterkunde)
```

Erstellung/Löschung von Unterkunden und Reseller-Abrechnung: siehe die [interaktive Referenz](/developers/api-reference).

## WebSocket: Logs live

```javascript
const ws = new WebSocket("wss://api.webgune.cloud/ws/services/:id/logs");
ws.onmessage = (e) => console.log(e.data); // eine Log-Zeile pro Nachricht
```

## WebSocket: Metriken live

```javascript
const ws = new WebSocket("wss://api.webgune.cloud/ws/projects/:id/metrics");
ws.onmessage = (e) => {
  const metrics = JSON.parse(e.data);
  // { "dienst-id": { cpu: 1.2, memory: 256 }, ... }
};
```

WebSockets erfordern eine Browser-Session: ein API-Schlüssel kann sich nicht damit verbinden (siehe [API-Schlüssel](/docs/cles-api)).