Ces routes permettent à un programme de travailler avec les flux du moteur d’automatisation : conserver les flux dans un gestionnaire de versions et les déployer, revenir en arrière, suivre les exécutions et traiter les messages en échec. Le fonctionnement des flux dans l’application est expliqué dans Flows et Versions, testing and rollback.
Les chemins se trouvent sous https://<your host>/tenant/<tenantId>. Envoyez Authorization: Bearer <API key> à chaque appel ; voir Authentication. Les heures dans cette API sont exprimées en millisecondes depuis l’époque.
Permissions et clés d’API
| Permission | Rôle par défaut | Autorise |
|---|---|---|
automation.read | Admin | Lire les flux, les versions, les exécutions sans contenu des messages, les messages en échec sans leur entrée, les webhooks, l’utilisation |
automation.manage | Admin | Créer, enregistrer, déployer, supprimer, restaurer, tester, importer et exporter des flux ; rejouer et abandonner les messages en échec |
automation.manage_privileged | Admin | Déployer des flux contenant des blocs de niveau contrôle |
automation.debug | Admin | Voir le contenu des messages dans les exécutions et les messages en échec ; tester à partir des messages enregistrés et de l’état en direct |
Une clé d’API peut détenir les quatre. Un déploiement demande aussi les permissions dont les blocs du flux ont besoin : un bloc Send command nécessite la permission d’envoi du niveau de la commande (iot_rpc.send.basic, iot_rpc.send.privileged, iot_rpc.send.critical), et automation.manage_privileged lorsque la commande est à fort impact. Une méthode de commande brute nécessite iot_rpc.send.raw, que seul un Owner détient et qu’aucune clé ne peut obtenir ; une clé ne peut donc pas déployer un flux qui envoie des méthodes brutes.
Un flux appartient à un host : generic (le host General) ou iot (le host IoT). Voir Hosts, the root flow and profile root flows.
Routes
| Méthode | Chemin | Permission | Fonction |
|---|---|---|---|
| GET | /api/automation/flows | automation.read | Lister les flux |
| POST | /api/automation/flows | automation.manage | Créer un flux sous forme de premier brouillon (jamais déployé, désactivé) |
| GET | /api/automation/flows/{flowId} | automation.read | Le flux, son contenu déployé et son brouillon partagé |
| PUT | /api/automation/flows/{flowId} | automation.manage | Enregistrer le brouillon partagé |
| PATCH | /api/automation/flows/{flowId} | automation.manage | Modifier la description |
| DELETE | /api/automation/flows/{flowId} | automation.manage | Supprimer (restaurable pendant 7 jours) |
| DELETE | /api/automation/flows/{flowId}/draft | automation.manage | Abandonner le brouillon |
| POST | /api/automation/flows/{flowId}/restore | automation.manage | Restaurer un flux supprimé ; il revient désactivé |
| POST | /api/automation/flows/{flowId}/resume | automation.manage | Reprendre un flux suspendu |
| POST | /api/automation/flows/{flowId}/detach | automation.manage | Transformer le flux d’une règle en flux ordinaire, de façon définitive |
| GET | /api/automation/flows/{flowId}/versions | automation.read | Versions déployées, les plus récentes en premier, sans contenu |
| GET | /api/automation/flows/{flowId}/versions/{version} | automation.read | Une version avec son contenu |
| GET | /api/automation/flows/{flowId}/status | automation.read | Le statut en direct du flux en cours d’exécution |
| POST | /api/automation/deploy | automation.manage | Déployer des flux et des opérations, tout ou rien |
| POST | /api/automation/deploy/preflight | automation.manage | Ce que ferait le même déploiement, sans l’effectuer |
| POST | /api/automation/test | automation.manage | Exécuter une fois le brouillon enregistré, à blanc |
| GET | /api/automation/debug/runs?flowId= | automation.read | Exécutions enregistrées d’un flux |
| GET | /api/automation/debug/runs/{runId} | automation.read | Une exécution avec ses étapes |
| GET | /api/automation/flows/{flowId}/hooks | automation.read | Les webhooks du flux |
| POST | /api/automation/flows/{flowId}/hooks/{nodeId}/rotate | automation.manage | Un nouveau secret pour un webhook |
| GET | /api/automation/dlq | automation.read | Messages en échec |
| POST | /api/automation/dlq/{entryId}/replay | automation.manage | Rejouer un message en échec |
| DELETE | /api/automation/dlq/{entryId} | automation.manage | Abandonner un message en échec |
| GET | /api/automation/export?ids= | automation.manage | Exporter les flux déployés sous forme de fichier |
| POST | /api/automation/import | automation.manage | Prévisualiser, puis valider, un import |
| DELETE | /api/automation/import/{batchId} | automation.manage | Annuler un import |
| GET, POST | /api/automation/emergency-stop | lecture : automation.read ; modification : automation.manage | L’arrêt d’urgence |
| GET | /api/automation/hosts | automation.read | Les hosts et l’autorisation de votre organisation à les utiliser |
| GET | /api/automation/blocks?host= | automation.read | Les blocs disponibles sur un host |
| GET | /api/automation/usage | automation.read | Les exécutions, étapes et temps de script du mois en cours, et les flux par rapport à votre forfait |
Lister et lire les flux
GET /api/automation/flows pagine à partir de 1, 50 lignes par défaut, au maximum 100. Filtres : host, kind, state (listes séparées par des virgules ; les états sont running, disabled, invalid, not_approved, paused), enabled, owned (true pour les flux de règles, false pour les flux ordinaires), updatedFrom / updatedTo (jours), search, deleted=true (les flux supprimés des 7 derniers jours), ids. Champs de tri : name, slug, host, kind, state, enabled, version, updatedAt, createdAt, deletedAt, sortOrder. La réponse est { "flows": [...], "data": [...], "total": n, "page": 1, "pageSize": 50 } ; data contient les mêmes lignes.
Une ligne de flux contient flowId, host, slug (l’identifiant fixe du flux, ^[a-z0-9_-]{1,32}$), name, description, enabled, state, stateReason, version (la version déployée, 0 avant le premier déploiement), draftRev, deletedAt, createdAt, updatedAt, et ownerModule pour un flux que possède la carte Rules.
GET /api/automation/flows/{flowId} répond { "flow", "current", "draft", "permissions" } : current est la version déployée avec son content, draft le brouillon partagé, et permissions indique lesquelles de automation.manage, automation.manage_privileged et automation.debug détient l’appelant.
Contenu, brouillons et création d’un flux
Le contenu d’un flux est { "id": "<slug>", "name": "…", "nodes": [...], "edges": [...] }. Un nœud est { "id", "type", "params", "name"?, "disabled"? } ; une arête est { "from", "from_port", "to" }. Les types de blocs et leurs paramètres sont listés par GET /api/automation/blocks?host=generic et décrits à partir de Trigger blocks. Le moyen le plus simple d’obtenir un contenu valide est de construire un flux dans l’éditeur, puis de le lire avec GET /api/automation/flows/{flowId}.
- Créer :
POST /api/automation/flowsavechost,kind(flow),slug,name(100 caractères au maximum),descriptionettemplatefacultatifs. Répond201 { "flow" }. Un slug déjà utilisé renvoie409 slug_taken. - Enregistrer le brouillon :
PUT /api/automation/flows/{flowId}avec{ "draftRev": n, "draft": <content> }, oùdraftRevest la révision que vous avez lue. Répond{ "draftRev" }avec la nouvelle révision ; envoyez-la avec votre prochaine sauvegarde. Si quelqu’un a enregistré entre-temps :409 { "error": "conflict", "draftRev", "by", "at", "theirs" }. Un brouillon ne s’exécute jamais.
Déployer
POST /api/automation/deploy déploie un nombre quelconque de flux et d’opérations en une seule fois, tout ou rien.
| Champ | Signification |
|---|---|
items | Flux à déployer : host, kind, content, enabled, note facultatif (500 caractères au maximum). Pour un flux existant, flowId et baseVersion (la version que vous avez lue ; 0 si elle n’a jamais été déployée). Sans flowId, un nouveau flux est créé. |
ops | Opérations : { "op": "enable", "flowId" }, disable, delete, { "op": "rollback", "flowId", "version" }, resume, set_root, unset_root |
confirm | Vos confirmations, par slug de flux : { "<slug>": { "check": true } } ou { "<slug>": { "typed": "<flow name>" } } |
100 éléments et 100 opérations au maximum ; le contenu de chaque flux à 1 MiB au maximum. Envoyez enabled explicitement sur chaque élément.
curl -X POST "https://<your host>/tenant/<tenantId>/api/automation/deploy" \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"items":[{"flowId":"9e8f…","baseVersion":4,"host":"generic","kind":"flow","enabled":true,"note":"Raise the threshold","content":{"id":"tank-alert","name":"Tank alert","nodes":[],"edges":[]}}]}'
La réponse est { "deployRev", "versions": [ { "flowId", "slug", "kind", "version", "approved" } ], "plan", "dropped", "warnings"?, "notified" }. notified: false signifie que la modification est enregistrée et que les workers la prennent en compte dans la minute.
Confirmations
Un flux contenant des blocs à risque doit être confirmé, comme dans la boîte de dialogue de déploiement de l’éditeur. Sans confirmation, le déploiement répond 428 :
{ "error": "confirm", "need": [ { "flow": "tank-alert", "name": "Tank alert", "level": "typed", "kinds": ["external"], "reasons": [ { "node": "n4", "type": "action.rpc", "risk": "external", "text": "…" } ], "permission": "automation.manage" } ] }
Renvoyez le même corps avec confirm : { "check": true } pour le niveau check, ou { "typed": "Tank alert" } (le nom du flux, exactement) pour le niveau typed. Une approbation est reportée au déploiement suivant du même contenu par le même membre : redéployer un contenu inchangé ne demande donc rien.
Utilisez POST /api/automation/deploy/preflight avec le même corps pour voir la réponse sans déployer : rien n’est écrit, verrouillé ni audité.
Versions et restauration
GET .../versions répond { "versions": [ { "version", "at", "by", "note", "mode", "hashShort", "approvedBy" } ] }. Pour revenir en arrière, déployez { "ops": [ { "op": "rollback", "flowId": "9e8f…", "version": 3 } ] }. Une restauration est une nouvelle version avec l’ancien contenu et nécessite les mêmes permissions et confirmations. La durée de conservation des versions est indiquée dans Versions, tests et restauration.
Tester le brouillon
POST /api/automation/test exécute le brouillon enregistré une fois, à blanc : les blocs qui agissent à l’extérieur indiquent ce qu’ils feraient, et rien n’est écrit ni envoyé.
{ "flowId": "9e8f…", "mode": "flow", "nodeId": "trigger-1", "input": { "msgType": "inject", "payload": { "level": 92 }, "originator": { "type": "tenant", "id": "<tenantId>" } } }
mode vaut flow (entrée par le déclencheur nodeId) ou node (exécute uniquement nodeId). Au lieu d’un message, input peut être { "sample": "declaration" } (l’exemple du bloc) ou, avec automation.debug, { "sample": "last_run" } ou { "fromRun": { "runId", "step" } }. La réponse contient steps, outputs, would, errors, ms, truncated et state. Un test s’arrête après 2 secondes ou 200 étapes. Chaque membre peut lancer 10 tests par minute : au-delà, 429 rate_limited avec Retry-After.
Exécutions et statut
GET /api/automation/debug/runs?flowId=<flowId or slug> liste les exécutions enregistrées, les plus récentes en premier. Filtres : nodeId, status (ok, error, left_open, dropped), msgType, originatorType, originatorId, port, from et to (millisecondes), limit (100 au maximum) et cursor (le next de la page précédente). Sans automation.debug, les lignes sont renvoyées sans contenu des messages. Seul ce que conserve le niveau d’enregistrement du flux est listé ; voir Dépannage des flux. Un troisième scan simultané dans votre organisation répond 429.
GET /api/automation/flows/{flowId}/status répond { "status" } : lignes d’état des nœuds, compteurs, débit et file d’attente tels que le flux en cours d’exécution les a last signalés, ou null avant le premier signalement. Le flux en direct de l’éditeur est réservé aux personnes connectées ; un programme interroge plutôt cette route.
Webhooks
GET /api/automation/flows/{flowId}/hooks liste les déclencheurs webhook d’un flux déployé et activé : { "hooks": [ { "nodeId", "hookId", "auth", "reply", "path" } ] }. La réponse ne contient jamais de secret.
POST .../hooks/{nodeId}/rotate génère un nouveau secret et l’affiche une seule fois : { "hookId", "secret", "previousValidHours": 24 }. L’ancien secret reste valide pendant 24 heures ; envoyez { "revokePrevious": true } pour le révoquer immédiatement. Un webhook de type session n’a pas de secret (409 no_secret).
Un programme qui appelle un webhook n’utilise pas de clé d’API : il utilise le secret propre au hook, comme décrit à la rubrique Webhook de Blocs déclencheurs.
Messages en échec
GET /api/automation/dlq liste les messages en échec, les plus récents en premier, pageSize jusqu’à 200 (par défaut 50). Pour la page suivante, passez next comme before (ou comme after lorsque vous triez par firstSeenAt:asc) ; next vaut null en fin de file. Filtres : reason (tenant_backlog, decode_failed, poison, host_refused, run_abandoned, retries_exhausted, expired), flow (un slug), host (par défaut generic). La réponse contient total, byReason (compté sur les 900 plus récents), entries et next. Chaque entrée contient id, reason, error, firstSeenAt, deliveries et, avec automation.debug, l’entrée d’origine dans fields.
POST /api/automation/dlq/{entryId}/replayrépond{ "replayed": true, "entryId" };404 gonesi elle a déjà été rejouée ou supprimée,404 unreadablesi son entrée est endommagée,429 backpressureavecRetry-After: 30.DELETE /api/automation/dlq/{entryId}répond{ "discarded": true }.
Ajoutez ?host=iot pour la file de l’hôte IoT. Un rejeu peut répéter un travail que la première tentative a déjà effectué ; voir Protections et messages en échec.
Export et import
- Export :
GET /api/automation/export?ids=<flowId>,<flowId>(de 1 à 100) répond{ "file", "skipped" }avec la version déployée de chaque flux et les connexions qu’il utilise. Les secrets ne figurent jamais dans le fichier. - Prévisualiser un import :
POST /api/automation/importavec{ "file", "choices": { "<slug>": "replace" }, "host": "generic" }.choicesvautreplace,copyouskippour chaque slug déjà existant. Rien n’est écrit ; la réponse{ "preview" }indique ce qui changerait, les confirmations qu’elle contient et unpreviewToken, valable 30 minutes. - Valider : le même corps plus
previewToken. Répond201 { "imported": { "importBatchId", … } }. Les flux importés arrivent désactivés et non approuvés ; saisissez à nouveau leurs secrets, puis déployez-les. - Annuler :
DELETE /api/automation/import/{importBatchId}(?dryRun=truepour voir le plan). Un flux déployé depuis l’import est laissé tel quel et listé dansskipped.
Le fichier peut peser 5 MiB au maximum. Une validation répond 409 stale_preview si un déploiement a eu lieu depuis la prévisualisation, 409 preview_expired après 30 minutes et 409 token_mismatch lorsque le jeton ne correspond pas au corps. Prévisualisez à nouveau dans chacun de ces cas.
Flux des règles de la carte Règles
Une règle de la carte Règles s’exécute sous forme de flux que l’API des flux liste avec ownerModule. Enregistrer, déployer, supprimer ou remplacer ce flux répond 409 owned_flow : modifiez plutôt la règle via l’API des règles. POST .../detach en fait un flux ordinaire de manière définitive : la règle est supprimée, et le flux compte alors dans la limite de flux de votre offre.
Erreurs
Les refus des routes d’automatisation portent un code error en plus des champs habituels :
| Statut | error | Signification |
|---|---|---|
| 400 | bad_request | La requête n’est pas valide. Un corps qui ne respecte pas les règles des champs donne Validation error avec issues. |
| 403 | forbidden | Un bloc du flux exige une permission que la clé ne possède pas (missing) |
| 403 | (aucun) | Une limite de l’offre : details.key max_flows ou max_script_blocks, avec limit, current, adding |
| 404 | not_found | « Flow not found. » ou « Flow version not found. » |
| 409 | conflict | Quelqu’un a déployé ou enregistré depuis votre lecture ; la réponse de déploiement contient conflicts et current |
| 409 | in_use, slug_taken, owned_flow, not_owned | Encore utilisé par une racine ou un autre flux (uses) ; le slug existe ; le flux d’une règle ; non le flux d’une règle |
| 410 | expired | « The flow was deleted too long ago to restore. » |
| 413 | « The request body is too large. » | |
| 422 | invalid | Le flux ne compile pas ; problems les liste une à une |
| 428 | confirm | Des confirmations manquent ; need les énumère |
| 503 | secrets_unavailable, owner_unavailable | Réessayer plus tard |
Voir Erreurs et limites de débit pour le corps d’erreur général et les limites de débit.
Limites
| Limite | Valeur |
|---|---|
| Éléments et opérations dans un même déploiement | 100 chacun |
| Contenu du flux, brouillon | 1 MiB chacun |
| Fichier d’import | 5 MiB |
| Note de déploiement | 500 caractères |
| Nom du flux, description | 100, 1 000 caractères |
| Tests | 10 par minute et par membre ; 2 secondes et 200 étapes chacun |
| Exécutions par page de liste | 100 |
| Messages en échec par page de liste | 200 |
| Restaurer un flux supprimé | Dans les 7 jours |
| Ancien secret de webhook après une rotation | 24 heures |
Les limites d’offre et les limites d’exécution des flux figurent dans Limites des flux.

