API-Übersicht

Einführung

Die ClawHosters-API ermöglicht es dir, deine Instanzen zu verwalten, Abrechnungen einzusehen und Add-ons programmatisch zu steuern. Es handelt sich um eine REST-API, die JSON akzeptiert und zurückgibt.

Basis-URL:

https://clawhosters.com/api/v1

Alle Endpunkte sind unter /api/v1 versioniert.

Authentifizierung

Die API verwendet Bearer-Token-Authentifizierung. Füge deinen API-Schlüssel im Authorization-Header jeder Anfrage hinzu.

Authorization: Bearer oc_live_dein_api_schlüssel_hier

Einen API-Schlüssel erstellen

1. Gehe zu Dashboard → Einstellungen → API-Schlüssel
2. Klicke auf API-Schlüssel erstellen
3. Gib deinem Schlüssel einen Namen (z.B. „Mein Skript")
4. Kopiere den Schlüssel sofort — er wird nur einmal angezeigt

API-Schlüssel beginnen mit dem Präfix oc_live_, gefolgt von einer eindeutigen Token-Zeichenkette. Bewahre deinen Schlüssel sicher auf und teile ihn nicht.

Schlüsselverwaltung

• Jedes Konto kann mehrere API-Schlüssel haben
• Schlüssel können jederzeit über das Dashboard widerrufen werden
• Der Widerruf ist sofort wirksam und kann nicht rückgängig gemacht werden
• Schlüssel unterstützen optionale Ablaufdaten

Ratenbegrenzung

Die API erzwingt ein Limit von 100 Anfragen pro Minute pro API-Schlüssel.

Jede Antwort enthält Rate-Limit-Header:

Wenn das Limit überschritten wird, gibt die API den Status 429 Too Many Requests zurück.

Anfrage-Format

Sende Anfragen mit Content-Type: application/json. Füge deinen API-Schlüssel im Authorization-Header hinzu.

Beispiel-Anfrage:

curl -X GET https://clawhosters.com/api/v1/instances \
  -H "Authorization: Bearer oc_live_dein_api_schlüssel_hier" \
  -H "Content-Type: application/json"

Beispiel-POST-Anfrage:

curl -X POST https://clawhosters.com/api/v1/instances/42/restart \
  -H "Authorization: Bearer oc_live_dein_api_schlüssel_hier" \
  -H "Content-Type: application/json"

Antwort-Format

Alle Antworten sind JSON. Erfolgreiche Antworten verpacken die Daten in einem data-Schlüssel.

Einzelne Ressource:

{
  "data": {
    "id": 42,
    "name": "my-bot",
    "status": "running"
  }
}

Liste mit Paginierung:

{
  "data": [
    { "id": 42, "name": "my-bot" },
    { "id": 43, "name": "test-bot" }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 3,
    "total_count": 52,
    "per_page": 25
  }
}

Fehler-Antworten

Fehler geben ein JSON-Objekt mit einem error-Schlüssel zurück, der einen maschinenlesbaren code und eine menschenlesbare message enthält.

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Validierungsfehler enthalten ein details-Feld:

{
  "error": {
    "code": "unprocessable_entity",
    "message": "Validation failed",
    "details": {
      "name": "is required"
    }
  }
}

HTTP-Statuscodes

Verfügbare Endpunkte

Health

Konto

Instanzen

Abrechnung

Add-ons

Backups

Versionierung

Die API ist über den URL-Pfad versioniert. Die aktuelle Version ist v1. Wenn Breaking Changes eingeführt werden, wird eine neue Version veröffentlicht, während die vorherige Version weiterhin verfügbar bleibt.

Verwandte Dokumentation

• Abrechnungsübersicht — Wie Abrechnung, Claws und Zahlungen funktionieren
• Instanz-Übersicht — Instanz-Lebenszyklus und Status
• Häufige Probleme beheben — Lösungen für häufige Probleme