Nouveau : le pare-feu IA surveille toute la plateforme et explique chaque incident en termes simples. Découvrez comment ça marche

API des flux

Créez, enregistrez, déployez, testez, restaurez, rétablissez et exportez des flux via REST, lisez leurs exécutions et webhooks, et rejouez les messages en échec.

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

PermissionRôle par défautAutorise
automation.readAdminLire les flux, les versions, les exécutions sans contenu des messages, les messages en échec sans leur entrée, les webhooks, l’utilisation
automation.manageAdminCréer, enregistrer, déployer, supprimer, restaurer, tester, importer et exporter des flux ; rejouer et abandonner les messages en échec
automation.manage_privilegedAdminDéployer des flux contenant des blocs de niveau contrôle
automation.debugAdminVoir 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éthodeCheminPermissionFonction
GET/api/automation/flowsautomation.readLister les flux
POST/api/automation/flowsautomation.manageCréer un flux sous forme de premier brouillon (jamais déployé, désactivé)
GET/api/automation/flows/{flowId}automation.readLe flux, son contenu déployé et son brouillon partagé
PUT/api/automation/flows/{flowId}automation.manageEnregistrer le brouillon partagé
PATCH/api/automation/flows/{flowId}automation.manageModifier la description
DELETE/api/automation/flows/{flowId}automation.manageSupprimer (restaurable pendant 7 jours)
DELETE/api/automation/flows/{flowId}/draftautomation.manageAbandonner le brouillon
POST/api/automation/flows/{flowId}/restoreautomation.manageRestaurer un flux supprimé ; il revient désactivé
POST/api/automation/flows/{flowId}/resumeautomation.manageReprendre un flux suspendu
POST/api/automation/flows/{flowId}/detachautomation.manageTransformer le flux d’une règle en flux ordinaire, de façon définitive
GET/api/automation/flows/{flowId}/versionsautomation.readVersions déployées, les plus récentes en premier, sans contenu
GET/api/automation/flows/{flowId}/versions/{version}automation.readUne version avec son contenu
GET/api/automation/flows/{flowId}/statusautomation.readLe statut en direct du flux en cours d’exécution
POST/api/automation/deployautomation.manageDéployer des flux et des opérations, tout ou rien
POST/api/automation/deploy/preflightautomation.manageCe que ferait le même déploiement, sans l’effectuer
POST/api/automation/testautomation.manageExécuter une fois le brouillon enregistré, à blanc
GET/api/automation/debug/runs?flowId=automation.readExécutions enregistrées d’un flux
GET/api/automation/debug/runs/{runId}automation.readUne exécution avec ses étapes
GET/api/automation/flows/{flowId}/hooksautomation.readLes webhooks du flux
POST/api/automation/flows/{flowId}/hooks/{nodeId}/rotateautomation.manageUn nouveau secret pour un webhook
GET/api/automation/dlqautomation.readMessages en échec
POST/api/automation/dlq/{entryId}/replayautomation.manageRejouer un message en échec
DELETE/api/automation/dlq/{entryId}automation.manageAbandonner un message en échec
GET/api/automation/export?ids=automation.manageExporter les flux déployés sous forme de fichier
POST/api/automation/importautomation.managePrévisualiser, puis valider, un import
DELETE/api/automation/import/{batchId}automation.manageAnnuler un import
GET, POST/api/automation/emergency-stoplecture : automation.read ; modification : automation.manageL’arrêt d’urgence
GET/api/automation/hostsautomation.readLes hosts et l’autorisation de votre organisation à les utiliser
GET/api/automation/blocks?host=automation.readLes blocs disponibles sur un host
GET/api/automation/usageautomation.readLes 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/flows avec host, kind (flow), slug, name (100 caractères au maximum), description et template facultatifs. Répond 201 { "flow" }. Un slug déjà utilisé renvoie 409 slug_taken.
  • Enregistrer le brouillon : PUT /api/automation/flows/{flowId} avec { "draftRev": n, "draft": <content> }, où draftRev est 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.

ChampSignification
itemsFlux à 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éé.
opsOpérations : { "op": "enable", "flowId" }, disable, delete, { "op": "rollback", "flowId", "version" }, resume, set_root, unset_root
confirmVos 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}/replay répond { "replayed": true, "entryId" } ; 404 gone si elle a déjà été rejouée ou supprimée, 404 unreadable si son entrée est endommagée, 429 backpressure avec Retry-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/import avec { "file", "choices": { "<slug>": "replace" }, "host": "generic" }. choices vaut replace, copy ou skip pour chaque slug déjà existant. Rien n’est écrit ; la réponse { "preview" } indique ce qui changerait, les confirmations qu’elle contient et un previewToken, valable 30 minutes.
  • Valider : le même corps plus previewToken. Répond 201 { "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=true pour voir le plan). Un flux déployé depuis l’import est laissé tel quel et listé dans skipped.

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 :

StatuterrorSignification
400bad_requestLa requête n’est pas valide. Un corps qui ne respecte pas les règles des champs donne Validation error avec issues.
403forbiddenUn 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
404not_found« Flow not found. » ou « Flow version not found. »
409conflictQuelqu’un a déployé ou enregistré depuis votre lecture ; la réponse de déploiement contient conflicts et current
409in_use, slug_taken, owned_flow, not_ownedEncore 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
410expired« The flow was deleted too long ago to restore. »
413« The request body is too large. »
422invalidLe flux ne compile pas ; problems les liste une à une
428confirmDes confirmations manquent ; need les énumère
503secrets_unavailable, owner_unavailableRé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

LimiteValeur
Éléments et opérations dans un même déploiement100 chacun
Contenu du flux, brouillon1 MiB chacun
Fichier d’import5 MiB
Note de déploiement500 caractères
Nom du flux, description100, 1 000 caractères
Tests10 par minute et par membre ; 2 secondes et 200 étapes chacun
Exécutions par page de liste100
Messages en échec par page de liste200
Restaurer un flux suppriméDans les 7 jours
Ancien secret de webhook après une rotation24 heures

Les limites d’offre et les limites d’exécution des flux figurent dans Limites des flux.