Neu: Die KI-Firewall überwacht die gesamte Plattform und erklärt jeden Vorfall in einfachen Worten. So funktioniert es

Flows-API

Flows über REST erstellen, speichern, deployen, testen, zurückrollen, wiederherstellen und exportieren, ihre Läufe und Webhooks lesen und fehlgeschlagene Nachrichten erneut abspielen.

Diese Routen ermöglichen es einem Programm, mit den Ababläufen der Automatisierungs-Engine zu arbeiten: Flows in der Versionsverwaltung halten und bereitstellen, zurückrollen, Läufe überwachen und fehlgeschlagene Nachrichten behandeln. Wie Flows in der App funktionieren, wird unter Flows und Versionen, Tests und Rollback erklärt.

Pfade liegen unter https://<your host>/tenant/<tenantId>. Senden Sie bei jedem Aufruf Authorization: Bearer <API key>; siehe Authentifizierung. Zeitangaben in dieser API sind Millisekunden seit der Epoche.

Berechtigungen und API-Schlüssel

BerechtigungStandardrolleErlaubt
automation.readAdminFlows, Versionen, Läufe ohne Nachrichteninhalte, fehlgeschlagene Nachrichten ohne ihre Eingabe, Webhooks und Nutzung lesen
automation.manageAdminFlows erstellen, speichern, bereitstellen, löschen, wiederherstellen, testen, importieren und exportieren; fehlgeschlagene Nachrichten erneut abspielen und verwerfen
automation.manage_privilegedAdminFlows mit Blöcken auf Steuerungsebene bereitstellen
automation.debugAdminNachrichteninhalte in Läufen und fehlgeschlagenen Nachrichten einsehen; aus aufgezeichneten Nachrichten und dem Live-Zustand testen

Ein API-Schlüssel kann alle vier Berechtigungen enthalten. Eine Bereitstellung verlangt außerdem die Berechtigungen, die die Blöcke des Flows benötigen: Ein Block Befehl senden benötigt die Sendeberechtigung der Stufe des Befehls (iot_rpc.send.basic, iot_rpc.send.privileged, iot_rpc.send.critical), und automation.manage_privileged, wenn der Befehl hohe Auswirkungen hat. Eine rohe Befehlsmethode benötigt iot_rpc.send.raw, die nur ein Owner hat und die kein Schlüssel haben kann; daher kann ein Schlüssel keinen Flow bereitstellen, der rohe Methoden sendet.

Ein Flow gehört zu einem Host: generic (der General-Host) oder iot (der IoT-Host). Siehe Hosts, der Root-Flow und Profil-Root-Flows.

Routen

MethodePfadBerechtigungFunktion
GET/api/automation/flowsautomation.readFlows auflisten
POST/api/automation/flowsautomation.manageEinen Flow als ersten Entwurf anlegen (nie bereitgestellt, aus)
GET/api/automation/flows/{flowId}automation.readDer Flow, sein bereitgestellter Inhalt und sein gemeinsamer Entwurf
PUT/api/automation/flows/{flowId}automation.manageDen gemeinsamen Entwurf speichern
PATCH/api/automation/flows/{flowId}automation.manageDie Beschreibung ändern
DELETE/api/automation/flows/{flowId}automation.manageLöschen (7 Tage wiederherstellbar)
DELETE/api/automation/flows/{flowId}/draftautomation.manageDen Entwurf verwerfen
POST/api/automation/flows/{flowId}/restoreautomation.manageEinen gelöschten Flow wiederherstellen; er kommt ausgeschaltet zurück
POST/api/automation/flows/{flowId}/resumeautomation.manageEinen pausierten Flow fortsetzen
POST/api/automation/flows/{flowId}/detachautomation.manageDen Flow einer Regel dauerhaft in einen normalen Flow umwandeln
GET/api/automation/flows/{flowId}/versionsautomation.readBereitgestellte Versionen, neueste zuerst, ohne Inhalt
GET/api/automation/flows/{flowId}/versions/{version}automation.readEine Version mit ihrem Inhalt
GET/api/automation/flows/{flowId}/statusautomation.readDer Live-Status des laufenden Flows
POST/api/automation/deployautomation.manageFlows und Operationen bereitstellen, alles oder nichts
POST/api/automation/deploy/preflightautomation.manageWas dieselbe Bereitstellung täte, ohne sie auszuführen
POST/api/automation/testautomation.manageDen gespeicherten Entwurf einmal als Testlauf ausführen
GET/api/automation/debug/runs?flowId=automation.readAufgezeichnete Läufe eines Flows
GET/api/automation/debug/runs/{runId}automation.readEin Lauf mit seinen Schritten
GET/api/automation/flows/{flowId}/hooksautomation.readDie Webhooks des Flows
POST/api/automation/flows/{flowId}/hooks/{nodeId}/rotateautomation.manageEin neues Geheimnis für einen Webhook
GET/api/automation/dlqautomation.readFehlgeschlagene Nachrichten
POST/api/automation/dlq/{entryId}/replayautomation.manageEine fehlgeschlagene Nachricht erneut abspielen
DELETE/api/automation/dlq/{entryId}automation.manageEine fehlgeschlagene Nachricht verwerfen
GET/api/automation/export?ids=automation.manageBereitgestellte Flows als Datei exportieren
POST/api/automation/importautomation.manageEinen Import vorab prüfen und dann übernehmen
DELETE/api/automation/import/{batchId}automation.manageEinen Import rückgängig machen
GET, POST/api/automation/emergency-stopLesen: automation.read; ändern: automation.manageDer Not-Aus
GET/api/automation/hostsautomation.readDie Hosts und ob Ihre Organisation sie nutzen darf
GET/api/automation/blocks?host=automation.readDie auf einem Host verfügbaren Blöcke
GET/api/automation/usageautomation.readLäufe, Schritte und Skriptzeit dieses Monats sowie Flows im Verhältnis zu Ihrem Tarif

Flows auflisten und lesen

GET /api/automation/flows paginiert ab 1, standardmäßig 50 Zeilen, höchstens 100. Filter: host, kind, state (kommagetrennte Listen; Zustände sind running, disabled, invalid, not_approved, paused), enabled, owned (true für Regel-Flows, false für normale), updatedFrom / updatedTo (Tage), search, deleted=true (die gelöschten Flows der letzten 7 Tage), ids. Sortierfelder: name, slug, host, kind, state, enabled, version, updatedAt, createdAt, deletedAt, sortOrder. Die Antwort ist { "flows": [...], "data": [...], "total": n, "page": 1, "pageSize": 50 }; data enthält dieselben Zeilen.

Eine Flow-Zeile hat flowId, host, slug (die feste ID des Flows, ^[a-z0-9_-]{1,32}$), name, description, enabled, state, stateReason, version (die bereitgestellte Version, 0 vor der ersten Bereitstellung), draftRev, deletedAt, createdAt, updatedAt und ownerModule für einen Flow, den die Regelkarte besitzt.

GET /api/automation/flows/{flowId} antwortet mit { "flow", "current", "draft", "permissions" }: current ist die bereitgestellte Version mit ihrem content, draft der gemeinsame Entwurf, und permissions zeigt, welche von automation.manage, automation.manage_privileged und automation.debug der Aufrufer besitzt.

Inhalt, Entwürfe und Anlegen eines Flows

Flow-Inhalt ist { "id": "<slug>", "name": "…", "nodes": [...], "edges": [...] }. Ein Knoten ist { "id", "type", "params", "name"?, "disabled"? }; eine Kante ist { "from", "from_port", "to" }. Die Blocktypen und ihre Parameter listet GET /api/automation/blocks?host=generic, beschrieben ab Trigger-Blöcke. Am einfachsten erhalten Sie gültigen Inhalt, indem Sie einen Flow im Editor erstellen und mit GET /api/automation/flows/{flowId} auslesen.

  • Erstellen: POST /api/automation/flows mit host, kind (flow), slug, name (bis zu 100 Zeichen), optional description und template. Antwortet mit 201 { "flow" }. Ein bereits verwendeter Slug ergibt 409 slug_taken.
  • Entwurf speichern: PUT /api/automation/flows/{flowId} mit { "draftRev": n, "draft": <content> }, wobei draftRev die Revision ist, die Sie gelesen haben. Antwortet mit { "draftRev" } mit der neuen Revision; senden Sie sie mit Ihrem nächsten Speichervorgang mit. Wenn jemand dazwischen gespeichert hat: 409 { "error": "conflict", "draftRev", "by", "at", "theirs" }. Ein Entwurf wird nie ausgeführt.

Deployen

POST /api/automation/deploy deployt beliebig viele Flows und Operationen auf einmal, alles oder nichts.

FeldBedeutung
itemsZu deployende Flows: host, kind, content, enabled, optional note (bis zu 500 Zeichen). Bei einem bestehenden Flow flowId und baseVersion (die Version, die Sie gelesen haben; 0, wenn sie nie deployt wurde). Ohne flowId wird ein neuer Flow angelegt.
opsOperationen: { "op": "enable", "flowId" }, disable, delete, { "op": "rollback", "flowId", "version" }, resume, set_root, unset_root
confirmIhre Bestätigungen, nach Flow-Slug: { "<slug>": { "check": true } } oder { "<slug>": { "typed": "<flow name>" } }

Bis zu 100 Items und 100 Operationen; der Inhalt jedes Flows höchstens 1 MiB. Senden Sie enabled bei jedem Item explizit mit.

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":[]}}]}'

Die Antwort lautet { "deployRev", "versions": [ { "flowId", "slug", "kind", "version", "approved" } ], "plan", "dropped", "warnings"?, "notified" }. notified: false bedeutet, dass die Änderung gespeichert ist und die Worker sie innerhalb einer Minute übernehmen.

Bestätigungen

Ein Flow mit riskanten Blöcken muss bestätigt werden, wie im Deploy-Dialog des Editors. Ohne Bestätigung antwortet das Deployment mit 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" } ] }

Senden Sie denselben Body erneut mit confirm: { "check": true } für die Stufe check oder { "typed": "Tank alert" } (der Name des Flows, genau so) für die Stufe typed. Eine Bestätigung gilt für das nächste Deployment desselben Inhalts durch dasselbe Mitglied weiter, sodass ein erneutes Deployen unveränderten Inhalts nichts abfragt.

Verwenden Sie POST /api/automation/deploy/preflight mit demselben Body, um die Antwort ohne Deployment zu sehen: Es wird nichts geschrieben, gesperrt oder protokolliert.

Versionen und Rollback

GET .../versions antwortet mit { "versions": [ { "version", "at", "by", "note", "mode", "hashShort", "approvedBy" } ] }. Zum Zurückrollen deployen Sie { "ops": [ { "op": "rollback", "flowId": "9e8f…", "version": 3 } ] }. Ein Rollback ist eine neue Version mit dem alten Inhalt und benötigt dieselben Berechtigungen und Bestätigungen. Wie lange Versionen aufbewahrt werden, steht unter Versions, testing and rollback.

Entwurf testen

POST /api/automation/test führt den gespeicherten Entwurf einmal als Probelauf aus: Blöcke, die nach außen wirken, zeigen an, was sie tun würden, und es wird nichts geschrieben oder gesendet.

{ "flowId": "9e8f…", "mode": "flow", "nodeId": "trigger-1", "input": { "msgType": "inject", "payload": { "level": 92 }, "originator": { "type": "tenant", "id": "<tenantId>" } } }

mode ist flow (Einstieg über den Trigger nodeId) oder node (nur nodeId ausführen). Statt einer Nachricht kann input { "sample": "declaration" } sein (das Beispiel des Blocks) oder, mit automation.debug, { "sample": "last_run" } bzw. { "fromRun": { "runId", "step" } }. Die Antwort enthält steps, outputs, would, errors, ms, truncated und state. Ein Test endet nach 2 Sekunden oder 200 Schritten. Jedes Mitglied darf 10 Tests pro Minute ausführen; danach 429 rate_limited mit Retry-After.

Läufe und Status

GET /api/automation/debug/runs?flowId=<flowId or slug> listet aufgezeichnete Läufe, neueste zuerst. Filter: nodeId, status (ok, error, left_open, dropped), msgType, originatorType, originatorId, port, from und to (Millisekunden), limit (höchstens 100) und cursor (das next der vorherigen Seite). Ohne automation.debug kommen die Zeilen ohne Nachrichteninhalte. Es werden nur Einträge aufgelistet, die die Aufzeichnungsstufe des Flows speichert; siehe Troubleshooting flows. Ein dritter gleichzeitiger Abruf in Ihrer Organisation antwortet mit 429.

GET /api/automation/flows/{flowId}/status antwortet mit { "status" }: Statuszeilen der Knoten, Zähler, Rate und Warteschlange, so wie der laufende Flow sie zuletzt gemeldet hat, oder null vor der ersten Meldung. Der Live-Stream des Editors ist nur für angemeldete Personen gedacht; ein Programm fragt stattdessen diese Route ab.

Webhooks

GET /api/automation/flows/{flowId}/hooks listet die Webhook-Trigger eines deployten, eingeschalteten Flows: { "hooks": [ { "nodeId", "hookId", "auth", "reply", "path" } ] }. Die Antwort enthält nie ein Geheimnis.

POST .../hooks/{nodeId}/rotate erzeugt ein neues Geheimnis und zeigt es einmalig an: { "hookId", "secret", "previousValidHours": 24 }. Das alte Geheimnis funktioniert weitere 24 Stunden; senden Sie { "revokePrevious": true }, um es sofort zu beenden. Ein Webhook vom Typ session hat kein Geheimnis (409 no_secret).

Ein Programm, das einen Webhook aufruft, verwendet keinen API-Schlüssel: Es verwendet das eigene Geheimnis des Hooks, wie unter Webhook in Trigger blocks beschrieben.

Fehlgeschlagene Nachrichten

GET /api/automation/dlq listet fehlgeschlagene Nachrichten, neueste zuerst, pageSize bis zu 200 (Standard 50). Für die nächste Seite übergeben Sie next als before (bzw. als after, wenn Sie nach firstSeenAt:asc sortieren); next ist am Ende der Warteschlange null. Filter: reason (tenant_backlog, decode_failed, poison, host_refused, run_abandoned, retries_exhausted, expired), flow (ein Slug), host (Standard generic). Die Antwort enthält total, byReason (gezählt über die neuesten 900), entries und next. Jeder Eintrag hat id, reason, error, firstSeenAt, deliveries und, mit automation.debug, die ursprüngliche Eingabe in fields.

  • POST /api/automation/dlq/{entryId}/replay antwortet mit { "replayed": true, "entryId" }; 404 gone, wenn sie bereits wiederholt oder verworfen wurde, 404 unreadable, wenn ihre Eingabe beschädigt ist, 429 backpressure mit Retry-After: 30.
  • DELETE /api/automation/dlq/{entryId} antwortet mit { "discarded": true }.

Fügen Sie ?host=iot hinzu, um die Warteschlange des IoT-Hosts abzurufen. Eine Wiederholung kann Arbeit wiederholen, die der erste Versuch bereits erledigt hat; siehe Protections and failed messages.

Export und Import

  • Export: GET /api/automation/export?ids=<flowId>,<flowId> (1 bis 100) antwortet mit { "file", "skipped" } mit der deployten Version jedes Flows und den verwendeten Verbindungen. Geheimnisse sind nie in der Datei enthalten.
  • Import vorab prüfen: POST /api/automation/import mit { "file", "choices": { "<slug>": "replace" }, "host": "generic" }. choices ist pro bereits vorhandenem Slug replace, copy oder skip. Es wird nichts geschrieben; die Antwort { "preview" } enthält, was sich ändern würde, die enthaltenen Bestätigungen und ein previewToken, das 30 Minuten gültig ist.
  • Übernehmen: derselbe Body plus previewToken. Antwort 201 { "imported": { "importBatchId", … } }. Importierte Flows werden ausgeschaltet und nicht freigegeben angelegt; Geheimnisse neu eingeben und die Flows anschließend deployen.
  • Rückgängig machen: DELETE /api/automation/import/{importBatchId} (?dryRun=true, um den Plan zu sehen). Ein Flow, der seit dem Import deployt wurde, bleibt unverändert und wird in skipped aufgeführt.

Die Datei darf höchstens 5 MiB groß sein. Eine Übernahme antwortet mit 409 stale_preview, wenn seit der Vorschau etwas deployt wurde, mit 409 preview_expired nach 30 Minuten und mit 409 token_mismatch, wenn das Token nicht zum Body passt. In jedem dieser Fälle erneut prüfen.

Flows aus der Karte Regeln (Rules)

Eine Regel der Karte Regeln läuft als Flow, den die Flow-API mit ownerModule auflistet. Speichern, Deployen, Löschen oder Ersetzen antwortet mit 409 owned_flow: Ändere die Regel stattdessen über die Rules API. POST .../detach macht sie dauerhaft zu einem normalen Flow: Die Regel wird gelöscht, und der Flow zählt danach gegen das Flow-Limit deines Tarifs.

Fehler

Ablehnungen der Automation-Routen enthalten neben den üblichen Feldern einen error-Code:

StatuserrorBedeutung
400bad_requestDie Anfrage ist nicht gültig. Ein Body, der die Feldregeln verletzt, ergibt Validation error mit issues.
403forbiddenEin Block des Flows benötigt eine Berechtigung, die der Schlüssel nicht besitzt (missing)
403(keine)Ein Plan-Limit: details.key max_flows oder max_script_blocks, mit limit, current, adding
404not_found„Flow not found.“ oder „Flow version not found.“
409conflictSeit deinem Lesen wurde deployt oder gespeichert; die Deploy-Antwort enthält conflicts und current
409in_use, slug_taken, owned_flow, not_ownedWird noch von einem Root oder einem anderen Flow verwendet (uses); der Slug existiert; ein Flow einer Regel; kein Flow einer Regel
410expired„The flow was deleted too long ago to restore.“
413„The request body is too large.“
422invalidDer Flow lässt sich nicht kompilieren; problems listet jedes Problem auf
428confirmBestätigungen fehlen; need listet sie auf
503secrets_unavailable, owner_unavailableSpäter erneut versuchen

Den allgemeinen Fehler-Body und die Rate-Limits findest du unter Fehler und Rate-Limits.

Limits

LimitWert
Blöcke und Operationen in einem Deployje 100
Flow-Inhalt, Entwurfje 1 MiB
Importdatei5 MiB
Deploy-Notiz500 Zeichen
Flow-Name, Beschreibung100, 1.000 Zeichen
Tests10 pro Minute und Mitglied; je 2 Sekunden und 200 Schritte
Läufe pro Listenseite100
Fehlgeschlagene Nachrichten pro Listenseite200
Gelöschten Flow wiederherstellenInnerhalb von 7 Tagen
Altes Webhook-Geheimnis nach einer Rotation24 Stunden

Plan-Limits und die Limits laufender Flows findest du unter Flow-Limits.