Skip to main content
Le API v2 sono in alpha e sono soggette a modifiche in qualsiasi momento.

​
Panoramica

L’API di analisi v2 è la nuova generazione dell’API di analisi di Devin Desktop. Espone i dati di consumo (crediti e ACU) tramite endpoint REST chiari, con filtri tramite parametri di query, raggruppamento flessibile, paginazione basata su cursore e cache delle risposte.
Gli endpoint v2 sono attualmente disponibili con il prefisso /api/v2alpha mentre l’API è in fase di definizione finale. L’URL di base è https://server.codeium.com.

​
Novità in v2

La differenza principale rispetto a v1 è l’autenticazione.

​
Autenticazione

v2 utilizza l’autenticazione con token Bearer. Passa la tua credenziale nell’header Authorization anziché nel corpo della richiesta:
Sono accettati due tipi di credenziali: una API key dell’utente di servizio Devin (consigliata — la stessa chiave cog_ utilizzata per la Devin API) o una chiave di servizio Windsurf.

​
API key degli utenti di servizio Devin

Se gestisci già utenti di servizio Devin, non ti servono credenziali Windsurf separate:
  1. Crea un utente di servizio in Settings > Utenti di servizio (organizzazione) o Impostazioni Enterprise > Utenti di servizio (Enterprise)
  2. Assegnagli un ruolo personalizzato che includa l’ autorizzazione Use Local Analytics API (il ruolo Admin predefinito la include già)
  3. Genera un’API key per l’utente di servizio: inizia con cog_
  4. Usa questa chiave come token Bearer
I risultati riguardano l’intero account Devin a cui appartiene l’utente di servizio e metadata.team_id è l’identificatore del team Devin dell’account (devin-team$<account_id>).
Il filtro group_id è un concetto proprio dei team Windsurf e non è supportato dalle credenziali Devin — le richieste che combinano i due restituiscono 400 Bad Request.

​
Chiavi di servizio Windsurf

  1. Vai alla pagina Team Settings del tuo team
  2. Vai alla sezione “Service Keys”
  3. Crea una nuova chiave di servizio con l’autorizzazione Analytics Read
  4. Usa la chiave come token Bearer nell’header Authorization
Sono supportate chiavi di servizio con ambito di gruppo: quando una chiave è limitata a un gruppo, i risultati vengono automaticamente limitati a quel gruppo.
Tieni al sicuro queste credenziali e non esporle mai nel codice lato client o in repository pubblici.

​
Endpoint disponibili

​
Strategia di fatturazione

Le risposte si adattano alla strategia di fatturazione del team, indicata in metadata.billing_strategy:
  • CREDITS — le righe includono prompt_credits e flex_credits
  • ACU — le righe includono billed_acus
Il campo message_count viene sempre restituito, indipendentemente dalla strategia. Le risposte che restituiscono elenchi sono paginate. Quando sono disponibili altri dati, la risposta include un pagination.next_page_cursor; passalo di nuovo come parametro di query page_cursor per recuperare la pagina successiva. I cursori scadono dopo 24 ore.

​
Cache

Le risposte includono un header ETag. Nelle richieste successive, invialo di nuovo nell’header If-None-Match per ricevere un 304 Not Modified se i dati non sono cambiati.

​
Limiti di frequenza

Questi endpoint non sono destinati al monitoraggio dell’utilizzo in tempo reale. I dati vengono aggregati su base oraria e il limite di frequenza è basso (10 richieste all’ora per team). Usali per report periodici ed esportazioni in blocco, non per dashboard in tempo reale o per il tracciamento delle singole richieste.
Gli endpoint v2 sono soggetti a un limite di frequenza di 10 richieste all’ora per team. Se il limite viene superato, viene restituito 429 Too Many Requests con un header Retry-After. La paginazione di una query precedente (seguendo un next_page_cursor) non viene conteggiata ai fini del limite di frequenza — viene conteggiata solo la query iniziale per ciascun report. Il limite ridotto riflette il fatto che questi endpoint sono pensati per report periodici, non per il monitoraggio in tempo reale.