Panoramica API
Copia un prompt di configurazione con i passaggi di installazione e la guida markdown completa per questo plugin.
Questa è la documentazione dell'API pubblica del cloud di Capgo. L'API ti permette di gestire in modo programmatico le tue risorse Capgo, tra cui organizzazioni, dispositivi, canali e bundle. È progettata per essere RESTful e utilizza i metodi HTTP standard.
Autenticazione
Sezione intitolata “Autenticazione”Tutti gli endpoint di API richiedono autenticazione. Per autenticare le tue richieste, aggiungi la tua chiave API nel x-api-key header, oppure inviala come Authorization: Bearer YOUR_API_KEY.
Esempio:
curl -H "x-api-key: YOUR_API_KEY" https://api.capgo.app/organization/Il authorization header con la chiave grezza (senza Bearer prefisso) è ancora accettata per integrazioni legacy, ma x-api-key è l'header consigliato per tutti i tipi di chiave, incluse le chiavi hash sicure.
Gli agenti AI e altri client OAuth possono ottenere una chiave tramite OAuth 2.0 (autorizzazione code con PKCE e registrazione dinamica del client). L'issuer è https://capgo.app, con i metadati in https://capgo.app/.well-known/oauth-authorization-server. L'utente sceglie a quali organizzazioni concedere l'accesso; l'access token è una chiave Capgo API inviata come Bearer token.
Versionamento
Sezione intitolata “Versioning”La API è versionata per data. Fissa una versione con l' capgo_api header della richiesta:
curl -H "x-api-key: YOUR_API_KEY" -H "capgo_api: 2025-10-01" https://api.capgo.app/organization/Senza l'header ottieni la versione predefinita, attualmente 2025-10-01. Le modifiche all'interno di una versione sono additive: nuovi endpoint, nuovi parametri opzionali e nuovi campi di risposta. Un breaking change viene rilasciato come una nuova versione datata, e i client fissati su una data precedente mantengono il vecchio comportamento. Una versione sconosciuta o malformata restituisce 400 unsupported_capgo_api_version oppure 400 invalid_capgo_api_version.
Rimuovere un'operazione o un campo è un breaking change, quindi avviene solo in una nuova versione datata. Al momento non c'è nulla di deprecato. Quando lo sarà, l'operazione verrà contrassegnata deprecated: true nel Spec OpenAPI, le sue risposte conterranno un Deprecation header (RFC 9745) e un Sunset header (RFC 8594) con la data in cui termina il vecchio comportamento, e la modifica sarà annunciata nella note di rilascio.
Limitazione del numero di richieste
Sezione intitolata “Rate Limiting”API implementa il rate limiting per garantire un uso equo. I limiti attuali sono:
- 2.000 richieste al minuto per chiave API
- 20.000 richieste al minuto per chiave API sulle route di upload dei bundle
- 20 chiavi API non valide per indirizzo IP in 15 minuti, dopodiché l'IP viene bloccato per 15 minuti
Ogni risposta riporta la quota tramite gli RateLimit-Policy e RateLimit header (draft IETF):
RateLimit-Policy: "apikey";q=2000;w=60RateLimit: "apikey";r=1995;t=42q è la quota, w è la finestra in secondi, r sono le richieste rimanenti e t i secondi mancanti al reset della finestra. Se superi un limite, riceverai una risposta 429 (Too Many Requests) con un Retry-After header in secondi.
Modifiche del canale del dispositivo
Sezione intitolata “Modifiche del canale del dispositivo”I cambiamenti del canale del dispositivo utilizzano il plugin API e hanno limiti di prevenzione degli abusi separati applicabili a ogni piano, inclusi quelli di prova:
- Un dispositivo può effettuare fino a 5 richieste al secondo per ogni operazione sul canale (
set,get,delete, olist). Questo limite si applica all'app, al dispositivo e all'operazione. - Impostare lo stesso dispositivo sullo stesso canale più di una volta entro 60 secondi restituisce una risposta 429. Il passaggio a un canale diverso è consentito dopo il reset del limite al secondo.
- Un limite aggiuntivo di 1000 richieste di canale al minuto si applica a ogni app e indirizzo IP.
Questi limiti non valgono per l'intero account. Se il tuo channel switcher può tornare a un canale selezionato di recente, attendi la retryAfterSeconds durata indicata nella risposta 429 prima di riprovare.
Formato della risposta
Sezione intitolata “Formato della risposta”Tutte le risposte sono in formato JSON. Le risposte di successo includono tipicamente un oggetto data o un campo status . Le risposte di errore includono un error code leggibile dalla macchina, un message, e facoltativo moreInfo details.
Esempio di risposta di successo:
{ "status": "ok", "data": { ... }}Esempio di risposta di errore:
{ "error": "invalid_apikey", "message": "Invalid apikey", "moreInfo": {}}Endpoint disponibili
Sezione intitolata “Endpoint disponibili”Best practice
Sezione “Best practice”- Gestione degli errori: Controlla sempre le risposte di errore e gestiscile in modo appropriato
- Limitazione del numero di richieste: Implementa l'exponential backoff quando raggiungi i rate limit
- Caching: Cache le risposte quando opportuno per ridurre le chiamate a API
- Versionamento: Tieni traccia delle modifiche a API tramite il nostro changelog
Continua da API Overview
Sezione intitolata “Continua da API Overview”Se stai usando Panoramica API per pianificare i flussi di autenticazione e account, collegandolo a @capgo/capacitor-social-login per i dettagli di implementazione in @capgo/capacitor-social-login, @capgo/capacitor-passkey per i dettagli di implementazione in @capgo/capacitor-passkey, @capgo/capacitor-native-biometric per i dettagli di implementazione in @capgo/capacitor-native-biometric, Autenticazione a due fattori per i dettagli di implementazione in Two-factor authentication, e SSO (Enterprise) per i dettagli di implementazione in SSO (Enterprise).