Aperçu de API

Voici la documentation de l'API publique du cloud Capgo. L'API vous permet de gérer par programmation vos ressources Capgo, notamment les organisations, les appareils, les canaux et les bundles. Elle est conçue pour être RESTful et utilise les méthodes HTTP standard.

Authentification

Tous les endpoints API nécessitent une authentification. Pour authentifier vos requêtes, ajoutez votre clé API dans l' x-api-key header, ou envoyez-l’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é 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 les autres clients OAuth peuvent obtenir une clé via OAuth 2.0 (autorisation code avec PKCE et enregistrement dynamique du client). L'émetteur est https://capgo.app, avec les métadonnées à 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. Épinglez une version avec l' capgo_api en-tête de requête :

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

Sans cet 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 livré sous forme d'une nouvelle version datée, et les clients épinglé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 l' Spécification OpenAPI, ses réponses comporteront un Deprecation en-tête (RFC 9745) et un Sunset en-tête (RFC 8594) indiquant la date de fin de l'ancien comportement, et le changement sera annoncé dans les notes de release.

Limitation de débit

L’API applique une limitation de débit pour garantir un usage équitable. Voici les limites actuelles :

• 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 sur 15 minutes, après quoi l’IP est bloquée pendant 15 minutes

Chaque réponse indique le quota via les RateLimit-Policy et RateLimit en-têtes (draft IETF):

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

q est le quota, w la fenêtre en secondes, r 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 (Trop de requêtes) avec un Retry-After en-tête en secondes.

Modifications du canal de l'appareil

Les changements de canal d’appareil utilisent le plugin API et sont soumis à des limites anti-abus distinctes, applicables à tous les plans, 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 définie par application, appareil et opération.
• Affecter le même appareil au même canal plus d’une fois en 60 secondes renvoie une réponse 429. Le passage à un autre canal est autorisé une fois la limite par seconde réinitialisée.
• Une limite supplémentaire de 1 000 requêtes par canal et par minute s’applique à chaque application et adresse IP.

Ces limites ne s’appliquent pas à l’ensemble du 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 un data objet ou un status champ. Les réponses d’erreur incluent un error code, lisible par un humain message, et facultatif moreInfo détails.

Exemple de réponse de succès :

{
  "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 au niveau de l'organisation

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

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

Statistiques Accéder à des statistiques détaillées sur l'usage de l'app, le stockage et la consommation de bande passante

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

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

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

Bonnes pratiques

1. Gestion des erreurs: Vérifiez toujours les réponses d'erreur et gérez-les correctement
2. Limitation de débit: Implémentez un backoff exponentiel en cas de limitation de débit
3. Mise en cache: Mettre en cache les réponses si pertinent pour réduire les appels API
4. VersionnageSuivez les changements de API via notre changelog

Continuer depuis API Vue d'ensemble

Si vous utilisez Aperçu de API pour planifier les flux d'authentification et de compte, le connecter à @capgo/capacitor-social-login pour les détails d'implémentation dans @capgo/capacitor-social-login @capgo/capacitor-passkey pour les détails 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 dans l'authentification à deux facteurs, et SSO (Entreprise) pour les détails d'implémentation dans le SSO (Enterprise).

Santé des releases, erreurs et builds natifs

Utilisez le surveillance de API pour les diagnostics natifs et de l’updater, les logs avec métadonnées, les statistiques du dashboard de release live, ainsi que l’état et les instantanés de logs des builds natifs. Ces lectures sont également exposées par les deux serveurs MCP du compte.