Panoramica API

Questa è la documentazione della API pubblica del cloud di Capgo. La API ti permette di gestire programmaticamente le tue risorse Capgo, tra cui organizzazioni, dispositivi, canali e bundle. È progettata per essere RESTful e utilizza i classici metodi HTTP.

Autenticazione

Tutti gli endpoint API richiedono autenticazione. Per autenticare le richieste, aggiungi la tua chiave API nell' 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/

Get API key Genera la tua chiave API nel dashboard Capgo

Il authorization header con la chiave raw (senza Bearer prefisso) è ancora accettato per le integrazioni legacy, ma x-api-key è l'header raccomandato 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 (authorization code con PKCE e dynamic client registration). 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

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 o 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 Specifica OpenAPI, le risposte conterranno un Deprecation header (RFC 9745) e un Sunset header (RFC 8594) con la data di fine del vecchio comportamento; il cambiamento sarà annunciato nella note di rilascio.

sezione 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=60
RateLimit: "apikey";r=1995;t=42

q è la quota, w è la finestra in secondi, r sono le richieste rimanenti e t i secondi mancanti al reset della finestra. Se superi il limite, riceverai una risposta 429 (Too Many Requests) con un Retry-After header in secondi.

Cambio del canale del dispositivo

Il cambio del canale del dispositivo utilizza il plugin API e ha limiti di abuse-prevention separati che si applicano 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, o list). Questo limite è riferito all'app, al dispositivo e all'operazione.
• Impostare lo stesso dispositivo sullo stesso canale più di una volta in 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 si applicano all'intero account. Se il tuo channel switcher può tornare a un canale selezionato di recente, attendi il retryAfterSeconds durata indicata nella risposta 429 prima di riprovare.

Formato della risposta

Tutte le risposte sono in formato JSON. Le risposte di successo includono solitamente un data oggetto o un status campo. Le risposte di errore includono un error code leggibile dalle macchine, un messaggio messageleggibile dall'utente e eventuali moreInfo dettagli.

Esempio di risposta di successo:

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

Esempio di risposta di errore:

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

Endpoint disponibili

Organizzazioni Crea e gestisci le organizzazioni, aggiorna le impostazioni e configura i parametri a livello di organizzazione

Chiavi API Genera, elenca e revoca le chiavi API per un accesso sicuro alle API Capgo

Membri Gestisci i membri dell'organizzazione, i ruoli e i permessi

Statistiche Accedi ad analytics dettagliate su utilizzo dell'app, storage e consumo di banda

Canali Controlla i canali di update dell'app, i bundle (versioni) e le policy di aggiornamento

Dispositivi Monitora e gestisci i dispositivi che eseguono la tua app, inclusi bundle (versioni) e assegnazioni ai channel

Bundle Gestisci i bundle dell'app, inclusi upload, elenco e gestione dei bundle (versioni)

Best practice

1. Gestione degli errori: Controlla sempre le risposte di errore e gestiscile in modo appropriato
2. Limitazione del numero di richieste: Implementa l'exponential backoff quando raggiungi i rate limit
3. Caching: Cache le risposte quando opportuno per ridurre le chiamate a API
4. VersionamentoMonitora le modifiche di API tramite il nostro changelog

Continua dalla panoramica di API

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).