Migrazione da v1/v2 - Devin Docs

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 precedente API key con un utente di servizio:

Vai a Settings > Service users
Crea un utente di servizio con un ruolo appropriato
Genera una API key (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 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

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.

​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?