Automations

Lister les automations

GET /api/v1/automations
GET /api/v1/automations?workspaceId=<id>   # scoper à un workspace

Scope requis : automation:read · voir Workspaces pour scoper. La création (POST) et la génération (/generate) acceptent aussi un workspaceId (voir ci-dessous).

curl https://api.gurren.leandre.io/api/v1/automations \
  -H "x-api-key: gfac_votre_cle"

Réponse :

[
  {
    "_id": "665a1b2c3d4e5f6a7b8c9d0e",
    "name": "Login et extraction",
    "url": "https://example.com/login",
    "description": "Se connecte et extrait les données",
    "intent": "account.login",
    "domain": "example.com",
    "actions": [
      { "_id": "aaa...", "type": "fill", "name": "Email", "selector": "#email", "value": "user@test.com" },
      { "_id": "bbb...", "type": "click", "name": "Submit", "selector": "#submit" }
    ],
    "createdAt": "2024-06-01T10:00:00.000Z",
    "updatedAt": "2024-06-01T12:00:00.000Z"
  }
]

---

Créer une automation

POST /api/v1/automations

Scope requis : automation:write

Crée une automation à partir d'actions explicites.

Champ	Type	Requis	Description
url	string	oui	URL de départ.
name	string	oui	Nom de l'automation.
description	string	non	Description libre.
actions	array	non	Actions typées (type, name, selector, value, …). Les valeurs supportent {{param:clé}} / {{extract:clé}} / {{email}}.
blockAssets	boolean	non	Bloque images/CSS/polices/media (économise la bande passante proxy).
workspaceId	string	non	Workspace de destination (défaut : votre workspace par défaut).

curl -X POST https://api.gurren.leandre.io/api/v1/automations \
  -H "x-api-key: gfac_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/login",
    "name": "Login et extraction",
    "actions": [
      { "type": "fill", "name": "Email", "selector": "#email", "value": "{{param:email}}" },
      { "type": "fill", "name": "Mot de passe", "selector": "#password", "value": "{{param:password}}" },
      { "type": "click", "name": "Submit", "selector": "#submit" }
    ]
  }'

Réponse :

{
  "success": true,
  "automation": {
    "_id": "665a1b2c3d4e5f6a7b8c9d0e",
    "name": "Login et extraction",
    "url": "https://example.com/login",
    "actions": [ /* ... */ ]
  }
}

---

Générer une automation (IA)

POST /api/v1/automations/generate

Scope requis : automation:write

L'IA parcourt l'url et construit l'automation à partir d'une consigne en langage naturel. Pour résoudre et exécuter en une seule étape (avec données + génération-si-absente), voir plutôt les Intents.

Champ	Type	Requis	Description
url	string	oui	Page cible (point de départ imposé).
prompt	string	oui	Ce que l'automation doit accomplir.
workspaceId	string	non	Workspace de destination.

curl -X POST https://api.gurren.leandre.io/api/v1/automations/generate \
  -H "x-api-key: gfac_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "prompt": "Créer un compte avec les données fournies"
  }'

Réponse :

{
  "success": true,
  "automation": { "_id": "665a...", "name": "...", "actions": [ /* ... */ ] }
}

---

Mettre à jour une automation

PATCH /api/v1/automations/:id

Scope requis : automation:write

Met à jour les champs fournis (tous optionnels) : url, name, description, actions, intent, tags. Utile notamment pour taguer l'intent d'une automation créée manuellement afin qu'un intent-run la réutilise (match sur intent + domaine de l'url).

curl -X PATCH https://api.gurren.leandre.io/api/v1/automations/665a... \
  -H "x-api-key: gfac_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{ "intent": "job.apply", "name": "Candidature WTTJ" }'

Réponse :

{ "success": true, "automation": { "_id": "665a...", "intent": "job.apply", "name": "Candidature WTTJ" } }

---

Sentinels

Garde de session. Une automation peut porter une liste de sentinels : des gardes surveillées tout au long du run. Dès qu'une sentinelle détecte un piège (déconnexion / blocage — via URL, paramètre, sélecteur DOM ou cookie), elle bascule en cours d'exécution vers un flux de reconnexion rejoué sur la même page / même IP, puis reprend (ou relance) le run.

Les identifiants nécessaires à la reconnexion vivent chiffrés sur la session (voir persistToSession), pour reconnecter le bon compte par session.

Modèle d'une sentinelle

{
  "id": "s1",
  "name": "Déconnexion WTTJ",
  "enabled": true,
  "when": "between-actions",
  "match": {
    "urlPattern": "(login|sign_in)",
    "selectorAbsent": ".user-menu",
    "cookieMissing": ["session_id"]
  },
  "recovery": {
    "mode": "resume-at-url",
    "automationId": "665b...",
    "intent": "auth.login"
  },
  "maxRecoveries": 2,
  "cooldownMs": 3000
}

Champ	Type	Description
name	string	Nom de la garde.
enabled	boolean	Active/désactive (défaut true).
when	navigate | between-actions | both	Quand évaluer (défaut both).
match	object	Piège — champs combinés en ET (urlPattern regex, queryParam, selectorPresent, selectorAbsent, textContains, cookieMissing). Un match vide ne se déclenche jamais.
recovery.mode	restart | resume-at-url | resume-in-place	Reprise après reconnexion (défaut resume-at-url : revient à la dernière page stable puis rejoue l'action piégée).
recovery.automationId	string	Flux de reconnexion explicite…
recovery.intent	string	…sinon résolu par tag pour le domaine courant (défaut auth.login).
maxRecoveries	number	Plafond de reconnexions sur tout le run (défaut 2).
cooldownMs	number	Délai avant qu'une même sentinelle puisse se redéclencher (défaut 3000).

Enregistrer les sentinels

PATCH /api/v1/automations/:id/sentinels

curl -X PATCH https://api.gurren.leandre.io/api/v1/automations/665a.../sentinels \
  -H "x-api-key: gfac_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{ "sentinels": [ { "name": "Déconnexion WTTJ", "match": { "urlPattern": "(login|sign_in)" }, "recovery": { "automationId": "665b..." } } ] }'

Mise à jour ciblée : cet endpoint remplace uniquement les sentinels, indépendamment des actions. Les reconnexions déclenchées sont tracées dans recoveryEvents de l'exécution (voir Exécutions).

---

Statut d'une automation

GET /api/v1/automations/:id/status

Scope requis : automation:read

curl https://api.gurren.leandre.io/api/v1/automations/665a.../status \
  -H "x-api-key: gfac_votre_cle"

Réponse :

{
  "isRunning": false
}

---

Déclencher une automation

POST /api/v1/automations/:id/trigger

Scope requis : automation:execute

curl -X POST https://api.gurren.leandre.io/api/v1/automations/665a.../trigger \
  -H "x-api-key: gfac_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "values": { "0": "john@example.com" },
    "useProxy": true,
    "enableAI": false
  }'

Réponse :

{
  "success": true,
  "executionId": "777b2c3d4e5f6a7b8c9d0eee",
  "statusUrl": "/api/v1/executions/777b2c3d4e5f6a7b8c9d0eee"
}

L'automation s'exécute en arrière-plan. Utilisez l'executionId pour suivre la progression.

Voir Options de déclenchement pour le détail de tous les paramètres.

---

Mettre en file d'attente

POST /api/v1/automations/:id/enqueue

Scope requis : automation:execute

Contrairement au /trigger, l'enqueue place l'automation dans une file d'attente pour une exécution asynchrone. Vous pouvez fournir une URL de callback webhook.

curl -X POST https://api.gurren.leandre.io/api/v1/automations/665a.../enqueue \
  -H "x-api-key: gfac_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "values": { "0": "john@example.com" },
    "useProxy": true,
    "webhookUrl": "https://example.com/callback"
  }'

Réponse :

{
  "success": true,
  "jobId": "aaa1b2c3d4e5f6a7b8c9d0e1",
  "statusUrl": "/api/v1/jobs/aaa1b2c3d4e5f6a7b8c9d0e1"
}

Suivez le statut du job via l'endpoint /api/v1/jobs/:id. Voir File d'attente pour plus de détails.

---

Arrêter une automation

POST /api/v1/automations/:id/stop

Scope requis : automation:execute

curl -X POST https://api.gurren.leandre.io/api/v1/automations/665a.../stop \
  -H "x-api-key: gfac_votre_cle"

Réponse :

{
  "success": true,
  "message": "Stop requested"
}

L'arrêt est gracieux : l'action en cours se termine, puis l'exécution s'arrête (statut failed, erreur « stopped by user »). Le signal est propagé de façon fiable même en environnement multi-instances. Suivez l'état via GET /api/v1/executions/:id.