API Übersicht

Dies ist die Dokumentation der öffentlichen API der Capgo Cloud. Mit der API lassen sich Ihre Capgo-Ressourcen programmatisch verwalten, darunter Organisationen, Geräte, Kanäle und Bundles. Sie ist RESTful aufgebaut und nutzt die Standard-HTTP-Methoden.

Authentifizierung

Alle API-Endpunkte erfordern eine Authentifizierung. Füge deinen API-Schlüssel hinzu, um x-api-key Header hinzu oder sende ihn als Authorization: Bearer YOUR_API_KEY.

Beispiel:

curl -H "x-api-key: YOUR_API_KEY" https://api.capgo.app/organization/

API-Key abrufen Erstelle deinen API-Schlüssel im Capgo-Dashboard

Der authorization Header mit dem rohen Schlüssel (ohne Bearer Präfix) wird für Legacy-Integrationen weiterhin akzeptiert, aber x-api-key ist der empfohlene Header für alle Schlüsseltypen, einschließlich sicher gehashter Schlüssel.

KI-Agenten und andere OAuth-Clients können einen Schlüssel über OAuth 2.0 (Authorization code mit PKCE und dynamischer Client-Registrierung) abrufen. Der Issuer ist https://capgo.app, mit Metadaten unter https://capgo.app/.well-known/oauth-authorization-server. Der Nutzer wählt aus, welchen Organisationen er Zugriff gewährt, und das Access-Token ist ein Capgo API-Key, der als Bearer-Token gesendet wird.

Versionierung

Die API wird nach Datum versioniert. Eine Version wird mit dem capgo_api Request-Header festgelegt:

curl -H "x-api-key: YOUR_API_KEY" -H "capgo_api: 2025-10-01" https://api.capgo.app/organization/

Ohne den Header erhältst du die Standardversion, derzeit 2025-10-01. Änderungen innerhalb einer Version sind additiv: neue Endpoints, neue optionale Parameter und neue Response-Felder. Ein Breaking Change wird als neue datierte Version ausgeliefert, und Clients, die an ein älteres Datum gepinnt sind, behalten das alte Verhalten bei. Eine unbekannte oder fehlerhafte Version liefert 400 unsupported_capgo_api_version oder 400 invalid_capgo_api_version.

Das Entfernen einer Operation oder eines Felds ist ein Breaking Change und erfolgt daher nur in einer neuen datierten Version. Derzeit wird nichts deprecated. Wenn etwas deprecated wird, wird die Operation entsprechend markiert. deprecated: true im OpenAPI-Spec, deren Antworten ein Deprecation -Header (RFC 9745) und ein Sunset -Header (RFC 8594) mit dem Datum, an dem das alte Verhalten endet, enthalten. Die Änderung wird im Abschnitt Release Notes.

Rate Limiting

Die API implementiert Rate Limiting, um eine faire Nutzung sicherzustellen. Die aktuellen Limits sind:

• 2.000 Anfragen pro Minute pro API-Key
• 20.000 Anfragen pro Minute pro API-Key auf Bundle-Upload-Routen
• 20 ungültige API-Keys pro IP-Adresse innerhalb von 15 Minuten, danach wird die IP für 15 Minuten blockiert

Jede Antwort meldet die Quota über die RateLimit-Policy und RateLimit Header (IETF-Entwurf):

RateLimit-Policy: "apikey";q=2000;w=60
RateLimit: "apikey";r=1995;t=42

q ist die Quota, w das Zeitfenster in Sekunden, r die verbleibenden Anfragen und t die Sekunden, bis das Zeitfenster zurückgesetzt wird. Wenn Sie ein Limit überschreiten, erhalten Sie eine 429 (Too Many Requests)-Antwort mit einem Retry-After Header in Sekunden.

Channel-Änderungen pro Gerät

Änderungen des Gerätekanals verwenden das Plugin API und unterliegen separaten Missbrauchsschutzlimits, die für alle Pläne gelten, einschließlich Testphasen:

• Ein Gerät kann pro Kanaloperation maximal 5 Anfragen pro Sekunde senden (set, get, delete, oder list). Dieses Limit gilt für die App, das Gerät und die Operation.
• Wenn dasselbe Gerät innerhalb von 60 Sekunden mehr als einmal auf denselben Kanal gesetzt wird, wird eine 429-Antwort zurückgegeben. Ein Wechsel zu einem anderen Kanal ist nach dem Zurücksetzen des Sekundenlimits erlaubt.
• Ein zusätzliches Limit von 1000 Kanal-Anfragen pro Minute gilt für jede App und IP-Adresse.

Diese Limits gelten nicht kontoweit. Wenn Ihr Kanal-Wechsler zu einem kürzlich gewählten Kanal zurückkehren kann, warten Sie die retryAfterSeconds Dauer in der 429-Antwort ab, bevor Sie erneut versuchen.

Response-Format

Alle Antworten liegen im JSON-Format vor. Erfolgreiche Antworten enthalten in der Regel entweder ein data Objekt oder ein status Feld. Fehlerantworten enthalten einen maschinenlesbaren error code, eine für Menschen lesbare messageNachricht sowie optionale moreInfo Details.

Beispiel für eine Erfolgsantwort:

{
  "status": "ok",
  "data": { ... }
}

Beispiel für eine Fehlerantwort:

{
  "error": "invalid_apikey",
  "message": "Invalid apikey",
  "moreInfo": {}
}

Verfügbare Endpoints

Organisationen Organisationen erstellen und verwalten, Einstellungen anpassen und Konfigurationen auf Organisationsebene steuern

API Schlüssel API Keys generieren, auflisten und widerrufen für den sicheren Zugriff auf die Capgo API

Mitglieder Organisationsmitglieder, Rollen und Berechtigungen verwalten

Statistiken Detaillierte Analytics zu App-Nutzung, Speicherplatz und Bandbreitenverbrauch abrufen

Kanäle App-Update-Channels, Bundles (Versionen) und Update-Policies steuern

Geräte Geräte mit Ihrer App verwalten, inkl. Bundle- (Versions-) und Kanalzuweisungen

Bundles Verwalten Sie App-Bundles, einschließlich Upload, Auflistung und Verwaltung von Bundles (Versionen)

Best Practices

1. Fehlerbehandlung: Prüfen Sie immer auf Fehlerantworten und behandeln Sie diese entsprechend
2. Rate Limiting: Implementieren Sie exponentielles Backoff, wenn Sie auf Rate Limits stoßen
3. Caching: Cachen Sie Antworten, wo sinnvoll, um API-Aufrufe zu reduzieren
4. VersionierungVerfolge Änderungen an API in unserem Changelog

Weiterlesen: API Overview

Wenn du es nutzt API Übersicht Um Authentifizierungs- und Account-Flows zu planen, verbinde es mit @capgo/capacitor-social-login für die Implementierungsdetails in @capgo/capacitor-social-login, @capgo/capacitor-passkey für die Implementierungsdetails in @capgo/capacitor-passkey, @capgo/capacitor-native-biometric für die Implementierungsdetails in @capgo/capacitor-native-biometric, Zwei-Faktor-Authentifizierung für die Implementierungsdetails zur Zwei-Faktor-Authentifizierung, und SSO (Enterprise) für die Implementierungsdetails zu SSO (Enterprise).