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 clé d’API d'utilisateur de service (commence par cog_)
export DEVIN_API_KEY="cog_your_key_here"

# Requis : votre identifiant d'organisation (affiché en haut de Settings > API Devin)
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 en haut de la page Settings > API Devin, là où l’utilisateur de service a été provisionné).

É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 '{
    "title": "PR Review",
    "body": "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 de 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={
        "title": "PR Review",
        "body": "Review the PR for bugs, security issues, and style violations."
    }
).json()
print(f"Created playbook: {playbook['playbook_id']}")

Planifier des sessions automatisées

Créez des sessions récurrentes à l’aide d’une automatisation dotée d’un trigger schedule:recurring. Ce trigger accepte une seule condition rrule : une RRULE iCalendar évaluée en UTC (par exemple FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=13;BYMINUTE=0 pour les jours ouvrés à 9 h, heure de l’Est, pendant l’heure d’été). Nécessite l’autorisation ManageOrgAutomations.

Les anciens endpoints /schedules sont dépréciés. À compter du 24 septembre 2026, POST /v3/organizations/{org_id}/schedules renverra 403 pour les organisations migrées vers les automatisations. Consultez les notes de version de l’API.

Créer une automatisation planifiée

curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/automations" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekday test run",
    "run_as": {"type": "organization"},
    "triggers": [{
      "event_type": "schedule:recurring",
      "conditions": {"any": [{"all": [{
        "field": "rrule",
        "operator": "recurrence",
        "value": "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=13;BYMINUTE=0"
      }]}]}
    }],
    "actions": [{
      "type": "start_session",
      "prompt": "Run the test suite and report any failures"
    }]
  }'

Pour une exécution ponctuelle, utilisez un DTSTART avec COUNT=1, par exemple DTSTART:20260915T170000Z\nRRULE:FREQ=DAILY;COUNT=1. L’automatisation se déclenche une seule fois, puis se désactive automatiquement.

Lister, mettre à jour et supprimer

# Lister les automatisations
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/automations" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

# Désactiver une automatisation
curl -X PATCH "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/automations/$AUTOMATION_ID" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

# Supprimer une automatisation
curl -X DELETE "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/automations/$AUTOMATION_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 automatisation de vérification de santé quotidienne (09h00 UTC tous les jours)
automation = requests.post(
    f"{BASE}/organizations/{ORG_ID}/automations",
    headers=HEADERS,
    json={
        "name": "Daily health check",
        "run_as": {"type": "organization"},
        "triggers": [{
            "event_type": "schedule:recurring",
            "conditions": {"any": [{"all": [{
                "field": "rrule",
                "operator": "recurrence",
                "value": "FREQ=DAILY;BYHOUR=9;BYMINUTE=0"
            }]}]}
        }],
        "actions": [{
            "type": "start_session",
            "prompt": "Run the test suite and report any failures"
        }]
    }
).json()
print(f"Created automation: {automation['automation_id']}")

# Lister toutes les automatisations (l'endpoint renvoie jusqu'à 100 éléments par page)
automations = []
after = None
while True:
    page = requests.get(
        f"{BASE}/organizations/{ORG_ID}/automations",
        headers={"Authorization": f"Bearer {API_KEY}"},
        params={"after": after},
    ).json()
    automations.extend(page["items"])
    if not page["has_next_page"]:
        break
    after = page["end_cursor"]

for a in automations:
    status = "enabled" if a.get("enabled") else "disabled"
    print(f"  {a['automation_id']}: {a['name']} ({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

​Planifier des sessions automatisées

​Créer une automatisation planifiée

​Lister, mettre à jour et supprimer

​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

Planifier des sessions automatisées

Créer une automatisation planifiée

Lister, mettre à jour et supprimer

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