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

# Workflows courants

> Guides de workflows de bout en bout pour les cas d’usage courants de l’API

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.

<div id="setup">
  ## Configuration
</div>

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

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

***

<div id="getting-started-api-key-to-first-session">
  ## Premiers pas : de l’API key à la première session
</div>

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

<div id="step-1-verify-your-credentials">
  ### Étape 1 : Vérifiez vos identifiants
</div>

<Note>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.</Note>

```bash theme={null}
curl "https://api.devin.ai/v3/self" \
  -H "Authorization: Bearer $DEVIN_API_KEY"
```

Réponse :

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

<div id="step-2-list-your-organizations">
  ### Étape 2 : Lister vos organisations
</div>

**Les utilisateurs de service Enterprise** peuvent lister toutes les organisations :

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

<div id="step-3-create-a-session">
  ### Étape 3 : Créer une session
</div>

```bash theme={null}
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 :

```json theme={null}
{
  "session_id": "devin-abc123",
  "url": "https://app.devin.ai/sessions/devin-abc123",
  "status": "running"
}
```

<div id="step-4-poll-for-events">
  ### Étape 4 : Interroger périodiquement les événements
</div>

Surveillez la session en interrogeant périodiquement les messages :

```bash theme={null}
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions/devin-abc123/messages" \
  -H "Authorization: Bearer $DEVIN_API_KEY"
```

<div id="full-python-example">
  ### Exemple complet en Python
</div>

```python theme={null}
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)
```

***

<div id="downloading-session-attachments">
  ## Téléchargement des pièces jointes d’une session
</div>

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

<div id="step-1-get-the-session">
  ### Étape 1 : Récupérer la session
</div>

```bash theme={null}
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $DEVIN_API_KEY"
```

<div id="step-2-list-attachments">
  ### Étape 2 : Lister les pièces jointes
</div>

```bash theme={null}
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions/$SESSION_ID/attachments" \
  -H "Authorization: Bearer $DEVIN_API_KEY"
```

Réponse :

```json theme={null}
{
  "items": [
    {
      "attachment_id": "att_123",
      "name": "output.py",
      "url": "https://..."
    }
  ]
}
```

<div id="step-3-download">
  ### Étape 3 : Téléchargement
</div>

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

<div id="full-python-example">
  ### Exemple complet en Python
</div>

```python theme={null}
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)")
```

***

<div id="knowledge-playbook-management">
  ## Gestion de Knowledge et des playbooks
</div>

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

<div id="create-a-knowledge-note">
  ### Créer une note de Knowledge
</div>

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

<div id="list-knowledge-notes">
  ### Lister les notes de Knowledge
</div>

```bash theme={null}
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/knowledge/notes" \
  -H "Authorization: Bearer $DEVIN_API_KEY"
```

<div id="update-a-knowledge-note">
  ### Mettre à jour une note de Knowledge
</div>

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

<div id="delete-a-knowledge-note">
  ### Supprimer une note de Knowledge
</div>

```bash theme={null}
curl -X DELETE "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/knowledge/notes/$NOTE_ID" \
  -H "Authorization: Bearer $DEVIN_API_KEY"
```

<div id="create-a-playbook">
  ### Créer un playbook
</div>

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

<div id="full-python-example">
  ### Exemple complet en Python
</div>

```python theme={null}
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']}")
```

***

<div id="scheduling-automated-sessions">
  ## Planification des sessions automatisées
</div>

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

<div id="create-a-schedule">
  ### Créer une planification
</div>

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

<div id="list-schedules">
  ### Lister les planifications
</div>

```bash theme={null}
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/schedules" \
  -H "Authorization: Bearer $DEVIN_API_KEY"
```

<div id="update-a-schedule">
  ### Modifier une planification
</div>

```bash theme={null}
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
  }'
```

<div id="delete-a-schedule">
  ### Supprimer une planification
</div>

```bash theme={null}
curl -X DELETE "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/schedules/$SCHEDULE_ID" \
  -H "Authorization: Bearer $DEVIN_API_KEY"
```

<div id="full-python-example">
  ### Exemple complet en Python
</div>

```python theme={null}
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})")
```

***

<div id="hand-off-a-task-from-anywhere">
  ## Passer le relais pour une tâche depuis n’importe où
</div>

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

<div id="create-a-session-with-repo-context">
  ### Créer une session avec le contexte du dépôt
</div>

```bash theme={null}
# 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](#step-4-poll-for-events) ou dans l’[application web Devin](https://app.devin.ai).

<Warning>
  `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.
</Warning>

<Tip>
  Vous ne voulez pas mettre cela en place vous-même ? Le plugin open source [Devin Handoff](https://github.com/club-cog/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](/fr/work-with-devin/devin-handoff).
</Tip>

***

<div id="error-handling">
  ## Gestion des erreurs
</div>

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

```python theme={null}
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}")
```

<div id="support">
  ## Assistance
</div>

<Card title="Besoin d’aide ?">
  Pour toute question concernant l’API ou pour signaler des problèmes, envoyez un e-mail à [support@cognition.ai](mailto:support@cognition.ai)
</Card>