> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrazione da v1/v2

> Migra le tue integrazioni da API v1 o v2 all'API corrente

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.

<div id="whats-changing">
  ## Cosa cambia
</div>

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

<div id="step-1-create-a-service-user">
  ## Passaggio 1: Crea un utente di servizio
</div>

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

```bash theme={null}
# 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" ...
```

<Note>
  Le tue vecchie API key continueranno a funzionare durante il periodo di dismissione. Puoi eseguire la migrazione gradualmente.
</Note>

<div id="step-2-update-endpoint-urls">
  ## Passaggio 2: Aggiornare gli URL degli endpoint
</div>

<div id="session-endpoints">
  ### Endpoint delle sessioni
</div>

| 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}`        |

<div id="knowledge-endpoints">
  ### Endpoint di Knowledge
</div>

| 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}` |

<div id="playbook-endpoints">
  ### Endpoint dei playbook
</div>

| 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}` |

<div id="secret-endpoints">
  ### Endpoint dei secret
</div>

| 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}` |

<div id="enterprise-only-endpoints-new">
  ### Endpoint disponibili solo per Enterprise (nuovi)
</div>

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

<div id="step-3-update-pagination">
  ## Passaggio 3: Aggiorna la paginazione
</div>

L'API attuale usa una paginazione basata su cursore anziché su offset:

```bash theme={null}
# 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](/it/api-reference/concepts/pagination).

<div id="step-4-handle-response-format-changes">
  ## Passaggio 4: Gestire le modifiche del formato della risposta
</div>

<div id="session-status-values">
  ### Valori dello stato della sessione
</div>

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

<div id="error-responses">
  ### Risposte di errore
</div>

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

<div id="deprecation-timeline">
  ## Tempistiche di dismissione
</div>

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

<div id="need-help">
  ## Hai bisogno di aiuto?
</div>

Se riscontri problemi durante la migrazione, contatta il tuo canale di supporto Devin abituale oppure scrivici a [support@cognition.ai](mailto:support@cognition.ai).