Vai al contenuto principale
Questa guida consente di migrare le integrazioni esistenti da API v1 o v2 alle API correnti di Organization ed Enterprise. Le API legacy (v1 e v2) continueranno a funzionare durante il periodo di deprecazione, ma tutte le nuove funzionalità saranno disponibili solo nell’API corrente.

​
Cosa cambia

Areav1/v2 (legacy)API attuale
AutenticazioneAPI key (inizia con apk_user_ o apk_)Token utente di servizio (inizia con cog_)
Base URL/v1/*, /v2/*/v3/organizations/*, /v3/enterprise/*
PaginazioneBasata su offset (offset + limit)Basata su cursore (first + after)
ScopingStruttura piatta — tutti gli endpoint allo stesso livelloCon ambito organizzazione e ambito Enterprise
PermessiA livello di chiave (tutto o nulla)Basata sui ruoli con permessi granulari

​
Passaggio 1: Crea un utente di servizio

Sostituisci la tua precedente API key con un utente di servizio:
  1. Vai a Settings > Service users
  2. Crea un utente di servizio con un ruolo appropriato
  3. Genera una API key (inizia con cog_)
  4. Aggiorna l’integrazione per usare la nuova API key
# Prima (API key legacy)
curl -H "Authorization: Bearer apk_user_YOUR_LEGACY_KEY" ...

# Dopo (token service user)
curl -H "Authorization: Bearer cog_YOUR_SERVICE_USER_KEY" ...
Le tue vecchie API key continueranno a funzionare durante il periodo di dismissione. Puoi eseguire la migrazione gradualmente.

​
Passaggio 2: Aggiornare gli URL degli endpoint

​
Endpoint delle sessioni

Operazioneendpoint v1endpoint attuale
Crea sessionePOST /v1/sessionsPOST /v3/organizations/sessions
Elenca sessioniGET /v1/sessionsGET /v3/organizations/sessions
Recupera sessioneGET /v1/session/{session_id}GET /v3/organizations/sessions/{devin_id}
Invia messaggioPOST /v1/session/{session_id}/messagePOST /v3/organizations/sessions/{devin_id}/messages
Archivia sessione—POST /v3/organizations/sessions/{devin_id}/archive
Elimina sessione—DELETE /v3/organizations/sessions/{devin_id}

​
Endpoint di Knowledge

OperazioneEndpoint v1Endpoint corrente
Elenca KnowledgeGET /v1/knowledgeGET /v3/organizations/knowledge/notes
Crea KnowledgePOST /v1/knowledgePOST /v3/organizations/knowledge/notes
Aggiorna KnowledgePUT /v1/knowledge/{note_id}PUT /v3/organizations/knowledge/notes/{note_id}
Elimina KnowledgeDELETE /v1/knowledge/{note_id}DELETE /v3/organizations/knowledge/notes/{note_id}

​
Endpoint dei playbook

Operazioneendpoint v1/v2endpoint corrente
Elenca playbookGET /v1/playbooksGET /v3/organizations/playbooks
Crea playbookPOST /v1/playbooksPOST /v3/organizations/playbooks
Recupera playbookGET /v1/playbooks/{playbook_id}GET /v3/organizations/playbooks/{playbook_id}
Aggiorna playbookPUT /v1/playbooks/{playbook_id}PUT /v3/organizations/playbooks/{playbook_id}
Elimina playbookDELETE /v1/playbooks/{playbook_id}DELETE /v3/organizations/playbooks/{playbook_id}

​
Endpoint dei secret

OperazioneEndpoint v1Endpoint corrente
Elenca i secretGET /v1/secretsGET /v3/organizations/secrets
Crea un secretPOST /v1/secretsPOST /v3/organizations/secrets
Elimina un secretDELETE /v1/secrets/{secret_id}DELETE /v3/organizations/secrets/{secret_id}

​
Endpoint disponibili solo per Enterprise (nuovi)

Questi endpoint non hanno un equivalente v1/v2 — sono disponibili solo nell’API attuale:
  • GET /v3/enterprise/organizations — Elenca le organizzazioni
  • GET /v3/enterprise/audit-logs — Log di audit
  • GET /v3/enterprise/consumption/* — Dati di utilizzo e fatturazione
  • GET /v3/enterprise/metrics/* — Metriche di utilizzo
  • GET /v3/enterprise/members/users — Gestione utenti
  • GET /v3/enterprise/roles — Gestione dei ruoli
  • Provisioning degli utenti di servizio, elenchi di accesso IP, limiti di ACU e altro

​
Passaggio 3: Aggiorna la paginazione

L’API attuale usa una paginazione basata su cursore anziché su offset: 
# Prima (v1/v2 basato su offset)
curl "https://api.devin.ai/v1/sessions?offset=0&limit=25"

# Dopo (basato su cursore)
curl "https://api.devin.ai/v3/organizations/sessions?first=25"
# Poi utilizza `end_cursor` dalla risposta per la pagina successiva:
curl "https://api.devin.ai/v3/organizations/sessions?first=25&after=CURSOR_VALUE"
Per maggiori dettagli, consulta Pagination.

​
Passaggio 4: Gestire le modifiche del formato della risposta

​
Valori dello stato della sessione

L’API attuale restituisce informazioni di stato più dettagliate. Consulta la documentazione dell’endpoint per lo schema completo.

​
Risposte di errore

Il formato delle risposte di errore è coerente: codice di stato HTTP + corpo JSON con i dettagli dell’errore.

​
Tempistiche di dismissione

Le API key legacy mostrano un banner che ne segnala la dismissione nell’interfaccia delle impostazioni di Devin. Durante il periodo di transizione:
  • Ora: Le API key legacy continuano a funzionare. Le nuove organizzazioni potrebbero non avere accesso alla creazione di API key legacy.
  • Periodo di dismissione: Sia le API key legacy che i token degli utenti di servizio funzionano in parallelo.
  • Fine del ciclo di vita: Le API key legacy verranno rimosse a breve. Controlla regolarmente le impostazioni di Devin per eventuali annunci.
Consigliamo di eseguire la migrazione agli utenti di servizio il prima possibile per sfruttare il controllo degli accessi basato sui ruoli, l’attribuzione delle sessioni e le nuove funzionalità.

​
Hai bisogno di aiuto?

Se riscontri problemi durante la migrazione, contatta il tuo canale di supporto Devin abituale oppure scrivici a support@cognition.ai.