Migrazione da v1/v2

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

Area	v1/v2 (legacy)	API attuale
Autenticazione	API key (inizia con `apk_user_` o `apk_`)	Token utente di servizio (inizia con `cog_`)
Base URL	`/v1/`, `/v2/`	`/v3/organizations/`, `/v3/enterprise/`
Paginazione	Basata su offset (`offset` + `limit`)	Basata su cursore (`first` + `after`)
Scoping	Struttura piatta — tutti gli endpoint allo stesso livello	Con ambito organizzazione e ambito Enterprise
Permessi	A livello di chiave (tutto o nulla)	Basata sui ruoli con permessi granulari

Passaggio 1: Crea un utente di servizio

Sostituisci la tua API key legacy con un utente di servizio:

Vai a Settings > Devin API e apri la tab utente di servizio
Clicca su Provision service user e assegna un ruolo appropriato
Copia la API key mostrata dopo il provisioning (inizia con cog_)
Aggiorna l’integrazione per usare la nuova API key

# Prima (API key legacy)
curl -H "Authorization: Bearer apk_user_YOUR_LEGACY_KEY" ...

# Dopo (token utente di servizio)
curl -H "Authorization: Bearer cog_YOUR_SERVICE_USER_KEY" ...

Le tue API key legacy continueranno a funzionare durante il periodo di dismissione. Puoi eseguire la migrazione gradualmente.

Passaggio 2: Aggiornare gli URL degli endpoint

Endpoint delle sessioni

Operazione	endpoint v1	endpoint attuale
Crea sessione	`POST /v1/sessions`	`POST /v3/organizations/{org_id}/sessions`
Elenca sessioni	`GET /v1/sessions`	`GET /v3/organizations/{org_id}/sessions`
Recupera sessione	`GET /v1/session/{session_id}`	`GET /v3/organizations/{org_id}/sessions/{devin_id}`
Invia messaggio	`POST /v1/session/{session_id}/message`	`POST /v3/organizations/{org_id}/sessions/{devin_id}/messages`
Archivia sessione	—	`POST /v3/organizations/{org_id}/sessions/{devin_id}/archive`
Elimina sessione	—	`DELETE /v3/organizations/{org_id}/sessions/{devin_id}`

Endpoint di Knowledge

Operazione	Endpoint v1	Endpoint attuale
Elenca Knowledge	`GET /v1/knowledge`	`GET /v3/organizations/{org_id}/knowledge/notes`
Crea Knowledge	`POST /v1/knowledge`	`POST /v3/organizations/{org_id}/knowledge/notes`
Aggiorna Knowledge	`PUT /v1/knowledge/{note_id}`	`PUT /v3/organizations/{org_id}/knowledge/notes/{note_id}`
Elimina Knowledge	`DELETE /v1/knowledge/{note_id}`	`DELETE /v3/organizations/{org_id}/knowledge/notes/{note_id}`

Endpoint dei playbook

Operazione	endpoint v1/v2	endpoint attuale
Elenca playbook	`GET /v1/playbooks`	`GET /v3/organizations/{org_id}/playbooks`
Crea playbook	`POST /v1/playbooks`	`POST /v3/organizations/{org_id}/playbooks`
Recupera playbook	`GET /v1/playbooks/{playbook_id}`	`GET /v3/organizations/{org_id}/playbooks/{playbook_id}`
Aggiorna playbook	`PUT /v1/playbooks/{playbook_id}`	`PUT /v3/organizations/{org_id}/playbooks/{playbook_id}`
Elimina playbook	`DELETE /v1/playbooks/{playbook_id}`	`DELETE /v3/organizations/{org_id}/playbooks/{playbook_id}`

Endpoint dei secret

Operazione	Endpoint v1	Endpoint attuale
Elenca i secret	`GET /v1/secrets`	`GET /v3/organizations/{org_id}/secrets`
Crea un secret	`POST /v1/secrets`	`POST /v3/organizations/{org_id}/secrets`
Elimina un secret	`DELETE /v1/secrets/{secret_id}`	`DELETE /v3/organizations/{org_id}/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/$DEVIN_ORG_ID/sessions?first=25"
# Poi utilizza `end_cursor` dalla risposta per la pagina successiva:
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/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.

Introduzione

Concetti

Ciclo di vita dell'agente

Gestione del contesto

Gestione degli ambienti

Automazione

Integrazioni

Analytics

Osservabilità

Devin per la Sicurezza

Infrastruttura

Identità e accessi

Configurazione

API legacy v1

API legacy v2

Cosa cambia

Passaggio 1: Crea un utente di servizio

Passaggio 2: Aggiornare gli URL degli endpoint

Endpoint delle sessioni

Endpoint di Knowledge

Endpoint dei playbook

Endpoint dei secret

Endpoint disponibili solo per Enterprise (nuovi)

Passaggio 4: Gestire le modifiche del formato della risposta

Valori dello stato della sessione

Risposte di errore

Tempistiche di dismissione

Hai bisogno di aiuto?

​Cosa cambia

​Passaggio 1: Crea un utente di servizio

​Passaggio 2: Aggiornare gli URL degli endpoint

​Endpoint delle sessioni

​Endpoint di Knowledge

​Endpoint dei playbook

​Endpoint dei secret

​Endpoint disponibili solo per Enterprise (nuovi)

​Passaggio 3: Aggiorna la paginazione

​Passaggio 4: Gestire le modifiche del formato della risposta

​Valori dello stato della sessione

​Risposte di errore

​Tempistiche di dismissione

​Hai bisogno di aiuto?

Cosa cambia

Passaggio 1: Crea un utente di servizio

Passaggio 2: Aggiornare gli URL degli endpoint

Endpoint delle sessioni

Endpoint di Knowledge

Endpoint dei playbook

Endpoint dei secret

Endpoint disponibili solo per Enterprise (nuovi)

Passaggio 3: Aggiorna la paginazione

Passaggio 4: Gestire le modifiche del formato della risposta

Valori dello stato della sessione

Risposte di errore

Tempistiche di dismissione

Hai bisogno di aiuto?