Workflows courants - Devin Docs

Cette page présente des workflows de bout en bout courants avec l’API Devin. Chaque workflow inclut la séquence complète des appels d’API, avec des exemples de code. Pour les détails de chaque endpoint, consultez les pages pertinentes de la référence d’API.

Configuration

Définissez ces variables d’environnement avant d’exécuter un exemple :

# Requis : votre API key d'utilisateur de service (commence par cog_)
export DEVIN_API_KEY="cog_your_key_here"

# Requis : votre identifiant d'organisation (disponible dans Settings > Service Users)
export DEVIN_ORG_ID="your_org_id"

Premiers pas : de l’API key à la première session

Le workflow le plus courant — s’authentifier, récupérer les informations de votre compte et créer votre première session.

Étape 1 : Vérifiez vos identifiants

Les utilisateur de service limité au périmètre de l’organisation peuvent passer à l’Étape 3 — vous connaissez déjà l’ID de votre org sur la page Settings.

curl "https://api.devin.ai/v3/self" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Réponse :

{
  "principal_type": "service_user",
  "service_user_id": "service-user-abc123",
  "service_user_name": "CI Bot",
  "org_id": null
}

Étape 2 : Lister vos organisations

Les utilisateurs de service Enterprise peuvent lister toutes les organisations :

curl "https://api.devin.ai/v3/enterprise/organizations" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Les utilisateurs de service limités au périmètre de l’organisation connaissent déjà l’ID de leur org (cet ID figure sur la page Settings > Service Users où la clé a été créée).

Étape 3 : Créer une session

curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Create a Python script that analyzes CSV data"}'

Réponse :

{
  "session_id": "devin-abc123",
  "url": "https://app.devin.ai/sessions/devin-abc123",
  "status": "running"
}

Étape 4 : Interroger périodiquement les événements

Surveillez la session en interrogeant périodiquement les messages :

curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions/devin-abc123/messages" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Exemple complet en Python

import os
import time
import requests

API_KEY = os.environ["DEVIN_API_KEY"]
ORG_ID = os.environ["DEVIN_ORG_ID"]
BASE = "https://api.devin.ai/v3"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1. Vérifier les identifiants
me = requests.get(f"{BASE}/self", headers=HEADERS)
me.raise_for_status()
data = me.json()
print(f"Authenticated as: {data.get('service_user_name') or data.get('user_name')}")

# 2. Créer une session
session = requests.post(
    f"{BASE}/organizations/{ORG_ID}/sessions",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={"prompt": "Create a Python script that analyzes CSV data"}
).json()
print(f"Session: {session['url']}")

# 3. Interroger périodiquement jusqu'à la fin
while True:
    status = requests.get(
        f"{BASE}/organizations/{ORG_ID}/sessions/{session['session_id']}",
        headers=HEADERS
    ).json()["status"]
    print(f"Status: {status}")
    if status in ("exit", "error", "suspended"):
        break
    time.sleep(10)

Téléchargement des pièces jointes d’une session

Récupérez les fichiers produits par une session (journaux, captures d’écran, code généré, etc.).

Étape 1 : Récupérer la session

curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Étape 2 : Lister les pièces jointes

curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions/$SESSION_ID/attachments" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Réponse :

{
  "items": [
    {
      "attachment_id": "att_123",
      "name": "output.py",
      "url": "https://..."
    }
  ]
}

Étape 3 : Téléchargement

Utilisez l’url fournie dans la réponse de la pièce jointe pour télécharger directement le fichier.

Exemple complet en Python

import os
import requests

API_KEY = os.environ["DEVIN_API_KEY"]
ORG_ID = os.environ["DEVIN_ORG_ID"]
SESSION_ID = os.environ["SESSION_ID"]
BASE = "https://api.devin.ai/v3"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# Lister les pièces jointes
attachments = requests.get(
    f"{BASE}/organizations/{ORG_ID}/sessions/{SESSION_ID}/attachments",
    headers=HEADERS
).json()["items"]

# Télécharger chaque pièce jointe
for att in attachments:
    print(f"Downloading {att['name']}...")
    content = requests.get(att["url"]).content
    with open(att["name"], "wb") as f:
        f.write(content)
    print(f"  Saved {att['name']} ({len(content)} bytes)")

Gestion de Knowledge et des playbooks

Gérez le contexte et les instructions que Devin utilise d’une session à l’autre.

Créer une note de Knowledge

curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/knowledge/notes" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Coding standards",
    "trigger": "When writing code in any repository",
    "body": "Use TypeScript strict mode. Follow existing code style. Run lint before committing."
  }'

Lister les notes de Knowledge

curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/knowledge/notes" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Mettre à jour une note de Knowledge

curl -X PUT "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/knowledge/notes/$NOTE_ID" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Coding standards (updated)",
    "trigger": "When writing code in any repository",
    "body": "Use TypeScript strict mode. Follow existing code style. Run lint and type-check before committing."
  }'

Supprimer une note de Knowledge

curl -X DELETE "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/knowledge/notes/$NOTE_ID" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Créer un playbook

curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/playbooks" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "PR Review",
    "instructions": "Review the PR for bugs, security issues, and style violations. Leave inline comments."
  }'

Exemple complet en Python

import os
import requests

API_KEY = os.environ["DEVIN_API_KEY"]
ORG_ID = os.environ["DEVIN_ORG_ID"]
BASE = "https://api.devin.ai/v3"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Créer une note Knowledge
note = requests.post(
    f"{BASE}/organizations/{ORG_ID}/knowledge/notes",
    headers=HEADERS,
    json={
        "name": "Coding standards",
        "trigger": "When writing code in any repository",
        "body": "Use TypeScript strict mode. Follow existing code style."
    }
).json()
print(f"Created note: {note['note_id']}")

# Lister toutes les notes
notes = requests.get(
    f"{BASE}/organizations/{ORG_ID}/knowledge/notes",
    headers={"Authorization": f"Bearer {API_KEY}"}
).json()["items"]
print(f"Total notes: {len(notes)}")

# Créer un playbook
playbook = requests.post(
    f"{BASE}/organizations/{ORG_ID}/playbooks",
    headers=HEADERS,
    json={
        "name": "PR Review",
        "instructions": "Review the PR for bugs, security issues, and style violations."
    }
).json()
print(f"Created playbook: {playbook['playbook_id']}")

Planification des sessions automatisées

Créez des sessions récurrentes qui s’exécutent selon une planification définie.

Créer une planification

curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/schedules" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Run the test suite and report any failures",
    "cron_schedule": "0 9 * * 1-5",
    "timezone": "America/New_York"
  }'

Cela crée une planification qui s’exécute chaque jour ouvré à 9 h (heure de l’Est).

Lister les planifications

curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/schedules" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Modifier une planification

curl -X PATCH "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/schedules/$SCHEDULE_ID" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cron_schedule": "0 8 * * 1-5",
    "is_enabled": true
  }'

Supprimer une planification

curl -X DELETE "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/schedules/$SCHEDULE_ID" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Exemple complet en Python

import os
import requests

API_KEY = os.environ["DEVIN_API_KEY"]
ORG_ID = os.environ["DEVIN_ORG_ID"]
BASE = "https://api.devin.ai/v3"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Créer une planification de vérification de santé quotidienne
schedule = requests.post(
    f"{BASE}/organizations/{ORG_ID}/schedules",
    headers=HEADERS,
    json={
        "prompt": "Run the test suite and report any failures",
        "cron_schedule": "0 9 * * 1-5",
        "timezone": "America/New_York"
    }
).json()
print(f"Created schedule: {schedule['schedule_id']}")

# Lister toutes les planifications
schedules = requests.get(
    f"{BASE}/organizations/{ORG_ID}/schedules",
    headers={"Authorization": f"Bearer {API_KEY}"}
).json()["items"]

for s in schedules:
    status = "enabled" if s.get("is_enabled") else "disabled"
    print(f"  {s['schedule_id']}: {s['cron_schedule']} ({status})")

Passer le relais pour une tâche depuis n’importe où

Comme l’API Sessions crée une session cloud de Devin à partir d’une seule requête, n’importe quel outil, script ou agent de développement peut « passer le relais » du travail à Devin en regroupant le dépôt actuel, la branche et les modifications non commitées dans le prompt, afin que la session cloud reprenne là où vous vous êtes arrêté.

Créer une session avec le contexte du dépôt

# Construire le corps JSON avec jq afin que le diff brut — qui contient des guillemets,
# des barres obliques inverses et des sauts de ligne — soit correctement échappé en chaîne JSON valide.
curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg diff "$(git diff HEAD)" \
    '{prompt: "Repo: my-org/my-repo (branch: fix-flaky-tests)\nFix the flaky integration tests in CI.\n\nUncommitted changes:\n\($diff)"}')"

La session cloud clone le dépôt, applique le contexte de votre prompt et s’exécute dans sa propre VM avec un Shell, un Browser et un accès complet au dépôt. Suivez-la en interrogeant périodiquement les messages ou dans l’application web Devin.

git diff HEAD peut inclure des secrets non commités — des clés d’API, des tokens ou des modifications de .env — et le prompt est envoyé à la session cloud. Vérifiez votre diff, puis effectuez un commit, un stash ou supprimez les modifications sensibles avant de passer le relais.

Vous ne voulez pas mettre cela en place vous-même ? Le plugin open source Devin Handoff encapsule exactement ce flux — en détectant automatiquement le dépôt, la branche et le diff — pour vous permettre de passer le relais depuis Devin CLI, Claude Code, Codex, Cursor ou un simple script shell. Consultez Passer le relais à Devin.

Gestion des erreurs

Tous les exemples ci-dessus doivent inclure une gestion des erreurs en environnement de production. Voici un modèle réutilisable :

import requests

def api_request(method, url, headers, **kwargs):
    """Effectuer une requête API avec gestion standard des erreurs."""
    response = requests.request(method, url, headers=headers, **kwargs)
    try:
        response.raise_for_status()
        return response.json()
    except requests.exceptions.HTTPError as e:
        status = e.response.status_code
        if status == 401:
            raise Exception("Invalid or expired API key")
        elif status == 403:
            raise Exception("Service user lacks required permission")
        elif status == 404:
            raise Exception("Resource not found")
        elif status == 429:
            raise Exception("Rate limit exceeded — wait and retry")
        else:
            raise Exception(f"API error {status}: {e.response.text}")

Assistance

Besoin d’aide ?

Pour toute question concernant l’API ou pour signaler des problèmes, envoyez un e-mail à support@cognition.ai

​Configuration

​Premiers pas : de l’API key à la première session

​Étape 1 : Vérifiez vos identifiants

​Étape 2 : Lister vos organisations

​Étape 3 : Créer une session

​Étape 4 : Interroger périodiquement les événements

​Exemple complet en Python

​Téléchargement des pièces jointes d’une session

​Étape 1 : Récupérer la session

​Étape 2 : Lister les pièces jointes

​Étape 3 : Téléchargement

​Exemple complet en Python

​Gestion de Knowledge et des playbooks

​Créer une note de Knowledge

​Lister les notes de Knowledge

​Mettre à jour une note de Knowledge

​Supprimer une note de Knowledge

​Créer un playbook

​Exemple complet en Python

​Planification des sessions automatisées

​Créer une planification

​Lister les planifications

​Modifier une planification

​Supprimer une planification

​Exemple complet en Python

​Passer le relais pour une tâche depuis n’importe où

​Créer une session avec le contexte du dépôt

​Gestion des erreurs

​Assistance

Besoin d’aide ?

Configuration

Premiers pas : de l’API key à la première session

Étape 1 : Vérifiez vos identifiants

Étape 2 : Lister vos organisations

Étape 3 : Créer une session

Étape 4 : Interroger périodiquement les événements

Exemple complet en Python

Téléchargement des pièces jointes d’une session

Étape 1 : Récupérer la session

Étape 2 : Lister les pièces jointes

Étape 3 : Téléchargement

Exemple complet en Python

Gestion de Knowledge et des playbooks

Créer une note de Knowledge

Lister les notes de Knowledge

Mettre à jour une note de Knowledge

Supprimer une note de Knowledge

Créer un playbook

Exemple complet en Python

Planification des sessions automatisées

Créer une planification

Lister les planifications

Modifier une planification

Supprimer une planification

Exemple complet en Python

Passer le relais pour une tâche depuis n’importe où

Créer une session avec le contexte du dépôt

Gestion des erreurs

Assistance