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

# Migration depuis v1/v2

> Migrez vos intégrations de l’API v1 ou v2 vers l’API actuelle

Ce guide vous aide à migrer vos intégrations existantes de l’API v1 ou v2 vers les API Organization et Enterprise actuelles. Les anciennes API (v1 et v2) continueront de fonctionner pendant la période de dépréciation, mais toutes les nouvelles fonctionnalités ne sont disponibles que via l’API actuelle.

<div id="whats-changing">
  ## Ce qui change
</div>

| Domaine            | v1/v2 (anciennes versions)                      | API actuelle                                            |
| ------------------ | ----------------------------------------------- | ------------------------------------------------------- |
| **Authentication** | API keys (commencent par `apk_user_` ou `apk_`) | Jetons d’utilisateur de service (commencent par `cog_`) |
| **Base URL**       | `/v1/*`, `/v2/*`                                | `/v3/organizations/*`, `/v3/enterprise/*`               |
| **Pagination**     | Pagination par offset (`offset` + `limit`)      | Pagination par curseur (`first` + `after`)              |
| **Scoping**        | À plat — tous les endpoints au même niveau      | Portée organisationnelle et portée Enterprise           |
| **Permissions**    | Au niveau de la clé (tout ou rien)              | Basées sur les rôles avec des autorisations granulaires |

<div id="step-1-create-a-service-user">
  ## Étape 1 : Créer un utilisateur de service
</div>

Remplacez votre ancienne API key par un utilisateur de service :

1. Allez dans **Settings > Service users**
2. Créez un utilisateur de service avec un rôle adapté
3. Générez une API key (qui commence par `cog_`)
4. Mettez à jour votre intégration pour utiliser la nouvelle clé

```bash theme={null}
# Avant (API key héritée)
curl -H "Authorization: Bearer apk_user_YOUR_LEGACY_KEY" ...

# Après (jeton d'utilisateur de service)
curl -H "Authorization: Bearer cog_YOUR_SERVICE_USER_KEY" ...
```

<Note>
  Vos anciennes API keys continueront de fonctionner pendant la période de dépréciation. Vous pouvez migrer progressivement.
</Note>

<div id="step-2-update-endpoint-urls">
  ## Étape 2 : Mettre à jour les URL des endpoints
</div>

<div id="session-endpoints">
  ### Session endpoints
</div>

| Opération             | endpoint v1                             | endpoint actuel                                                |
| --------------------- | --------------------------------------- | -------------------------------------------------------------- |
| Créer une session     | `POST /v1/sessions`                     | `POST /v3/organizations/{org_id}/sessions`                     |
| Lister les sessions   | `GET /v1/sessions`                      | `GET /v3/organizations/{org_id}/sessions`                      |
| Récupérer une session | `GET /v1/session/{session_id}`          | `GET /v3/organizations/{org_id}/sessions/{devin_id}`           |
| Envoyer un message    | `POST /v1/session/{session_id}/message` | `POST /v3/organizations/{org_id}/sessions/{devin_id}/messages` |
| Archiver une session  | —                                       | `POST /v3/organizations/{org_id}/sessions/{devin_id}/archive`  |
| Supprimer une session | —                                       | `DELETE /v3/organizations/{org_id}/sessions/{devin_id}`        |

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

| Opération                          | endpoint v1                      | endpoint actuel                                               |
| ---------------------------------- | -------------------------------- | ------------------------------------------------------------- |
| Lister les éléments Knowledge      | `GET /v1/knowledge`              | `GET /v3/organizations/{org_id}/knowledge/notes`              |
| Créer un élément Knowledge         | `POST /v1/knowledge`             | `POST /v3/organizations/{org_id}/knowledge/notes`             |
| Mettre à jour un élément Knowledge | `PUT /v1/knowledge/{note_id}`    | `PUT /v3/organizations/{org_id}/knowledge/notes/{note_id}`    |
| Supprimer un élément Knowledge     | `DELETE /v1/knowledge/{note_id}` | `DELETE /v3/organizations/{org_id}/knowledge/notes/{note_id}` |

<div id="playbook-endpoints">
  ### Endpoints des playbooks
</div>

| Opération                 | endpoint v1/v2                       | endpoint actuel                                             |
| ------------------------- | ------------------------------------ | ----------------------------------------------------------- |
| Lister les playbooks      | `GET /v1/playbooks`                  | `GET /v3/organizations/{org_id}/playbooks`                  |
| Créer un playbook         | `POST /v1/playbooks`                 | `POST /v3/organizations/{org_id}/playbooks`                 |
| Récupérer un playbook     | `GET /v1/playbooks/{playbook_id}`    | `GET /v3/organizations/{org_id}/playbooks/{playbook_id}`    |
| Mettre à jour un playbook | `PUT /v1/playbooks/{playbook_id}`    | `PUT /v3/organizations/{org_id}/playbooks/{playbook_id}`    |
| Supprimer un playbook     | `DELETE /v1/playbooks/{playbook_id}` | `DELETE /v3/organizations/{org_id}/playbooks/{playbook_id}` |

<div id="secret-endpoints">
  ### Endpoints des secrets
</div>

| Opération           | endpoint v1                      | endpoint actuel                                         |
| ------------------- | -------------------------------- | ------------------------------------------------------- |
| Lister les secrets  | `GET /v1/secrets`                | `GET /v3/organizations/{org_id}/secrets`                |
| Créer un secret     | `POST /v1/secrets`               | `POST /v3/organizations/{org_id}/secrets`               |
| Supprimer un secret | `DELETE /v1/secrets/{secret_id}` | `DELETE /v3/organizations/{org_id}/secrets/{secret_id}` |

<div id="enterprise-only-endpoints-new">
  ### Points de terminaison réservés à l’Enterprise (nouveaux)
</div>

Ces points de terminaison n’ont pas d’équivalent en v1/v2 — ils ne sont disponibles que dans l’API actuelle :

* `GET /v3/enterprise/organizations` — Lister les organisations
* `GET /v3/enterprise/audit-logs` — Journaux d’audit
* `GET /v3/enterprise/consumption/*` — Données d’utilisation et de facturation
* `GET /v3/enterprise/metrics/*` — Métriques d’utilisation
* `GET /v3/enterprise/members/users` — Gestion des utilisateurs
* `GET /v3/enterprise/roles` — Gestion des rôles
* Provisionnement des utilisateurs de service, listes d’accès IP, plafonds d’ACU et plus encore

<div id="step-3-update-pagination">
  ## Étape 3 : Mettre à jour la pagination
</div>

L’API actuelle utilise une pagination par curseur au lieu d’une pagination par offset :

```bash theme={null}
# Avant (v1/v2 basé sur l'offset)
curl "https://api.devin.ai/v1/sessions?offset=0&limit=25"

# Après (pagination par curseur)
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions?first=25"
# Ensuite, utilisez `end_cursor` de la réponse pour la page suivante :
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions?first=25&after=CURSOR_VALUE"
```

Consultez [Pagination](/fr/api-reference/concepts/pagination) pour plus de détails.

<div id="step-4-handle-response-format-changes">
  ## Étape 4 : Gérer les modifications du format de réponse
</div>

<div id="session-status-values">
  ### Valeurs d'état de session
</div>

L'API actuelle fournit des informations d'état plus détaillées. Consultez la référence de l'endpoint pour connaître le schéma complet.

<div id="error-responses">
  ### Réponses d’erreur
</div>

Le format d’erreur est toujours le même : code de statut HTTP + corps JSON avec les détails de l’erreur.

<div id="deprecation-timeline">
  ## Calendrier d’obsolescence
</div>

Les API keys héritées affichent une bannière d’obsolescence dans l’interface des paramètres Devin. Pendant la période de transition :

* **Maintenant** : les API keys héritées continuent de fonctionner. Les nouvelles organisations peuvent ne pas avoir accès à la création de clés héritées.
* **Période d’obsolescence** : les clés héritées et les jetons d’utilisateur de service fonctionnent en parallèle.
* **Fin de vie** : les API keys héritées seront bientôt supprimées. Consultez régulièrement vos paramètres Devin pour suivre les annonces.

Nous vous recommandons de migrer vers les utilisateurs de service dès que possible afin de bénéficier du contrôle d’accès basé sur les rôles, de l’attribution de session et des nouvelles fonctionnalités.

<div id="need-help">
  ## Besoin d’aide ?
</div>

En cas de problème pendant la migration, contactez-nous via votre canal d’assistance Devin habituel ou écrivez-nous à [support@cognition.ai](mailto:support@cognition.ai).