Aperçu de API

Copiez un prompt de configuration avec les étapes d'installation et le guide markdown complet pour ce plugin.

Voici la documentation de l'API public du cloud Capgo. L'API vous permet de gérer par programmation vos ressources Capgo, incluant les organisations, les appareils, les canaux et les bundles. Il est conçu pour être RESTful et utilise les méthodes HTTP standards.

Authentification

Tous les endpoints de l'API nécessitent une authentification. Pour authentifier vos requêtes, ajoutez votre clé API dans la x-api-key header, ou l'envoyer en tant que Authorization: Bearer YOUR_API_KEY.

Exemple :

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

Obtenir une clé API Générez votre clé API dans le dashboard Capgo

Le authorization header avec la clé brute (sans Bearer préfixe) est toujours acceptée pour les intégrations existantes, mais x-api-key est l'en-tête recommandé pour tous les types de clés, y compris les clés hachées sécurisées.

Les agents IA et autres clients OAuth peuvent obtenir une clé via OAuth 2.0 (autorisation code avec PKCE et enregistrement dynamique de client). L'émetteur est https://capgo.app, avec les métadonnées sur https://capgo.app/.well-known/oauth-authorization-server. L'utilisateur choisit les organisations auxquelles accorder l'accès, et le token d'accès est une clé Capgo API envoyée en tant que Bearer token.

Versionnage

L’API est versionné par date. Fixez une version avec l'en-tête de capgo_api en-tête de la requête :

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

Sans l'en-tête, vous obtenez la version par défaut, actuellement 2025-10-01. Les changements au sein d'une version sont additifs : nouveaux endpoints, nouveaux paramètres optionnels et nouveaux champs de réponse. Un breaking change est déployé sous forme de nouvelle version datée, et les clients fixés sur une date antérieure conservent l'ancien comportement. Une version inconnue ou malformée renvoie 400 unsupported_capgo_api_version ou 400 invalid_capgo_api_version.

Supprimer une opération ou un champ est un breaking change, cela n'arrive donc que dans une nouvelle version datée. Rien n'est déprécié aujourd'hui. Le moment venu, l'opération sera marquée deprecated: true dans la Spécification OpenAPI, ses réponses contiendront un Deprecation header (RFC 9745) et un Sunset header (RFC 8594) indiquant la date de fin de l'ancien comportement, et le changement sera annoncé dans les notes de release.

Limitation du débit

API implémente la limitation du débit pour garantir un usage équitable. Les limites actuelles sont :

2 000 requêtes par minute par clé API
20 000 requêtes par minute par clé API sur les routes d'upload de bundle
20 clés API invalides par adresse IP en 15 minutes, après quoi l'IP est bloquée pendant 15 minutes

Chaque réponse indique le quota avec les RateLimit-Policy et RateLimit headers (IETF draft):

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

q est le quota, w est la fenêtre en secondes, r sont les requêtes restantes et t les secondes avant la réinitialisation de la fenêtre. Si vous dépassez une limite, vous recevrez une réponse 429 (Too Many Requests) avec un Retry-After en-tête en secondes.

Changements de canal de l'appareil

Les changements de canal de l'appareil utilisent le plugin API et possèdent des limites de prévention des abus distinctes qui s'appliquent à chaque plan, y compris les essais :

Un appareil peut effectuer jusqu'à 5 requêtes par seconde pour chaque opération de canal (set, get, delete, ou list). Cette limite est limitée à l'app, à l'appareil et à l'opération.
Assigner le même appareil au même canal plus d'une fois en 60 secondes renvoie une réponse 429. Passer à un canal différent est autorisé une fois la limite par seconde réinitialisée.
Une limite supplémentaire de 1000 requêtes de canal par minute s'applique à chaque app et adresse IP.

Ces limites ne sont pas globales au compte. Si votre sélecteur de canal peut revenir à un canal récemment sélectionné, attendez la retryAfterSeconds durée indiquée dans la réponse 429 avant de réessayer.

Format de la réponse

Toutes les réponses sont au format JSON. Les réponses réussies incluent généralement soit un data objet ou un status champ. Les réponses d'erreur incluent un error code lisible par une machine, un message, et optionnel moreInfo details.

Exemple de réponse réussie :

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

Exemple de réponse d'erreur :

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

Endpoints disponibles

Organisations Créer et gérer les organisations, mettre à jour les paramètres et gérer les configurations propres à l'organisation

Clés API Générer, lister et révoquer les clés API pour un accès sécurisé à Capgo API

Membres Gérer les membres, rôles et permissions de l'organisation

Statistiques Accédez à des analyses détaillées sur l'utilisation de l'app, le stockage et la consommation de bande passante

Canaux Gérer les canaux de mise à jour de l'app, les bundles (versions) et les politiques de mise à jour

Appareils Suivez et gérez les appareils exécutant votre application, y compris l'attribution des bundles (versions) et des canaux

Bundles Gérez les bundles de l'application, incluant l'upload, la liste et la gestion des bundles (versions)

Bonnes pratiques

Gestion des erreurs: Vérifiez toujours les réponses d'erreur et gérez-les correctement
Limitation du débit (Rate Limiting): Implémentez un backoff exponentiel lors de l'atteinte des limites de débit
Mise en cache: Cache responses when appropriate to reduce API calls
VersionnageSuivez les changements de API via notre changelog

Continuer depuis l'aperçu de API

Si vous utilisez Aperçu de API pour planifier l'authentification et les flux de comptes, connectez-l’à @capgo/capacitor-social-login pour le détail d'implémentation dans @capgo/capacitor-social-login, @capgo/capacitor-passkey pour le détail d'implémentation dans @capgo/capacitor-passkey, @capgo/capacitor-native-biometric pour les détails d'implémentation dans @capgo/capacitor-native-biometric, Authentification à deux facteurs pour les détails d'implémentation de l'authentification à deux facteurs, et SSO (Entreprise) pour les détails d'implémentation du SSO (Enterprise).