Intentions

L'API d'intention permet de décrire ce que vous voulez accomplir plutôt que de cibler une automation précise. Gurren résout l'intention contre votre pool d'automations (workspace) : s'il en existe une qui correspond au couple (intention, domaine), elle est réutilisée et exécutée ; sinon, une nouvelle est générée automatiquement.

Deux modes (comme pour les automations trigger / enqueue) :

POST /api/v1/intents/run       # immédiat : réutilisation → executionId tout de suite
POST /api/v1/intents/enqueue   # asynchrone (le "/nq") : renvoie un jobId, suivi par webhooks

Scope requis : automation:execute. Pour une intégration serveur, préférez /enqueue : réponse immédiate { jobId, statusUrl }, jamais bloquante, et tout l'avancement arrive en webhooks (intent.*, execution.*, job.*). Fournissez un webhookUrl dans le body.

Body

Tous les champs sont optionnels — au minimum, fournissez soit (intent + url), soit un prompt libre dont le modèle déduira l'intention et l'URL.

Champ	Type	Description
intent	string	Intention explicite au format category.verb (ex. account.signup). Déduite du prompt si absente.
url	string	URL cible. Déduite du prompt si absente.
prompt	string	Instruction libre : sert à inférer intent/url/paramètres quand ils ne sont pas explicites et décrit à la génération ce que l'automatisation doit accomplir (ex. « crée le compte puis complète tout l'onboarding »).
parameters	Record<string, any>	Données nommées injectées dans l'automation ({{param:clé}}).
dataBlocks	string[]	Blocs de données libres que le modèle peut parser en paramètres.
workspaceId	string	Pool d'automations dans lequel résoudre / taguer l'automation générée. À défaut, le workspace par défaut.
sessionId	string	Session navigateur à réutiliser pour l'exécution.
generationSessionId	string	Session à réutiliser pour la génération (chaînage opt-in, ex. login → puis publier). À défaut, la génération part d'une page vierge (aucune restauration automatique).
enableSelfHealing	boolean	Réparer en direct une étape cassée (voir Options de déclenchement).
captureAllSteps	boolean	Debug : capturer un screenshot après chaque étape (visible dans phases[].screenshotUrl de l'exécution).
blockAssets	boolean	Charger images/CSS/polices (par défaut bloqués). Mettre à false pour des captures fidèles en debug.
autoExecute	boolean	Si une automation doit être générée, l'exécuter immédiatement au lieu d'attendre validation (défaut false).
webhookUrl	string	(/enqueue uniquement) URL qui reçoit les webhooks job.* + intent.*.

Unicité : une automation est unique par couple (intention, domaine). La même intention peut donc cibler plusieurs sites.

Chaînage de sessions (génération) : une génération part toujours d'une page vierge par défaut (un template doit être propre et réutilisable). Une génération qui construit un état (login, compte) sauvegarde sa session ; pour qu'une génération dépendante reparte de cet état (ex. « publier » après « se connecter »), passe explicitement son generationSessionId. La continuité « bot » au fil des runs, elle, se fait à l'exécution via sessionId.

Réponses

Un seul champ outcome indique ce que la résolution a décidé (au lieu d'un ensemble de drapeaux booléens) :

outcome	Signification
executed	une automation existante a matché → elle s'exécute (executionId)
generated	aucune correspondance → une nouvelle a été générée et enregistrée, en attente de validation (pas exécutée)
needs_generation	génération différée — l'appelant (UI) la streame lui-même

outcome: executed — réutilisée → exécutée

{
  "outcome": "executed",
  "automationId": "665a1b2c3d4e5f6a7b8c9d0e",
  "executionId": "777b2c3d4e5f6a7b8c9d0eee",
  "domain": "example.com"
}

Suivez l'exécution via GET /api/v1/executions/:executionId.

outcome: generated — aucune correspondance → générée

Une nouvelle automation est générée et enregistrée, en attente de validation (elle n'est pas soumise automatiquement).

{
  "outcome": "generated",
  "automationId": "665a1b2c3d4e5f6a7b8c9d0e",
  "domain": "example.com",
  "message": "Aucune automatisation n'existait pour cette intention. Une nouvelle a été générée et enregistrée — vérifie-la puis lance-la pour soumettre."
}

Vérifiez l'automation puis déclenchez-la avec POST /api/v1/automations/:id/trigger.

/enqueue — asynchrone (recommandé pour l'API)

La réponse est immédiate ; l'intent est traité en file d'attente. Tout l'avancement arrive en webhooks.

{ "success": true, "jobId": "888c...", "statusUrl": "/api/v1/jobs/888c..." }

Cycle de webhooks (selon l'issue) :

• Réutilisation : intent.received → intent.resolved → execution.started → automation.completed/failed → intent.completed { outcome: "executed", executionId }
• Génération (défaut) : intent.received → intent.generation.started → intent.generation.completed → intent.completed { outcome: "generated", automationId }
• Génération + autoExecute: true : intent.received → intent.generation.started → intent.generation.completed → execution.started → automation.completed/failed → intent.completed { outcome: "executed", executionId }

Suivi aussi via GET /api/v1/jobs/:id (et GET /api/v1/executions/:id quand il y a eu une exécution).

Corrélation : quand il y a exécution, tous les webhooks d'exécution (execution.started, automation.completed/failed) portent le jobId d'origine (dès le premier event execution.started) en plus de l'executionId — tu peux donc relier l'exécution à ton job sans appel supplémentaire.

Exemple

curl -X POST https://api.gurren.leandre.io/api/v1/intents/run \
  -H "x-api-key: gfac_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Crée un compte sur welcometothejungle.com",
    "parameters": { "email": "john@example.com", "password": "SecureP@ss123" },
    "enableSelfHealing": true
  }'

Ou de façon explicite :

curl -X POST https://api.gurren.leandre.io/api/v1/intents/run \
  -H "x-api-key: gfac_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "account.signup",
    "url": "https://www.welcometothejungle.com/",
    "parameters": { "email": "john@example.com", "password": "SecureP@ss123" },
    "prompt": "Crée le compte PUIS complète tout l onboarding : renseigne le profil, les préférences de poste et la localisation jusqu au tableau de bord. Ne postule à aucune offre."
  }'