Migration depuis v1/v2

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.

Ce qui change

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

Étape 1 : Créer un utilisateur de service

Remplacez votre ancienne API key par un utilisateur de service :

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

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

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

Étape 2 : Mettre à jour les URL des endpoints

Session endpoints

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

Endpoints Knowledge

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

Endpoints des playbooks

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

Endpoints des secrets

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

Points de terminaison réservés à l’Enterprise (nouveaux)

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

Étape 3 : Mettre à jour la pagination

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

# 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 pour plus de détails.

Étape 4 : Gérer les modifications du format de réponse

Valeurs d’état de session

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.

Réponses d’erreur

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

Calendrier d’obsolescence

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.

Besoin d’aide ?

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

Premiers pas

Concepts

Cycle de vie de l’agent

Gestion du contexte

Gestion de l’environnement

Automatisation

Intégrations

Analyse

Observabilité

Devin pour la sécurité

Infrastructure

Identité et accès

Configuration

Ancienne API v1

Ancienne API v2

Migration depuis v1/v2

Ce qui change

Étape 1 : Créer un utilisateur de service

Étape 2 : Mettre à jour les URL des endpoints

Session endpoints

Endpoints Knowledge

Endpoints des playbooks

Endpoints des secrets

Points de terminaison réservés à l’Enterprise (nouveaux)

Étape 4 : Gérer les modifications du format de réponse

Valeurs d’état de session

Réponses d’erreur

Calendrier d’obsolescence

Besoin d’aide ?

​Ce qui change

​Étape 1 : Créer un utilisateur de service

​Étape 2 : Mettre à jour les URL des endpoints

​Session endpoints

​Endpoints Knowledge

​Endpoints des playbooks

​Endpoints des secrets

​Points de terminaison réservés à l’Enterprise (nouveaux)

​Étape 3 : Mettre à jour la pagination

​Étape 4 : Gérer les modifications du format de réponse

​Valeurs d’état de session

​Réponses d’erreur

​Calendrier d’obsolescence

​Besoin d’aide ?

Ce qui change

Étape 1 : Créer un utilisateur de service

Étape 2 : Mettre à jour les URL des endpoints

Session endpoints

Endpoints Knowledge

Endpoints des playbooks

Endpoints des secrets

Points de terminaison réservés à l’Enterprise (nouveaux)

Étape 3 : Mettre à jour la pagination

Étape 4 : Gérer les modifications du format de réponse

Valeurs d’état de session

Réponses d’erreur

Calendrier d’obsolescence

Besoin d’aide ?