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
| Berechtigung | Standardrolle | Erlaubt |
|---|---|---|
automation.read | Admin | Flows, Versionen, Läufe ohne Nachrichteninhalte, fehlgeschlagene Nachrichten ohne ihre Eingabe, Webhooks und Nutzung lesen |
automation.manage | Admin | Flows erstellen, speichern, bereitstellen, löschen, wiederherstellen, testen, importieren und exportieren; fehlgeschlagene Nachrichten erneut abspielen und verwerfen |
automation.manage_privileged | Admin | Flows mit Blöcken auf Steuerungsebene bereitstellen |
automation.debug | Admin | Nachrichteninhalte 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
| Methode | Pfad | Berechtigung | Funktion |
|---|---|---|---|
| GET | /api/automation/flows | automation.read | Flows auflisten |
| POST | /api/automation/flows | automation.manage | Einen Flow als ersten Entwurf anlegen (nie bereitgestellt, aus) |
| GET | /api/automation/flows/{flowId} | automation.read | Der Flow, sein bereitgestellter Inhalt und sein gemeinsamer Entwurf |
| PUT | /api/automation/flows/{flowId} | automation.manage | Den gemeinsamen Entwurf speichern |
| PATCH | /api/automation/flows/{flowId} | automation.manage | Die Beschreibung ändern |
| DELETE | /api/automation/flows/{flowId} | automation.manage | Löschen (7 Tage wiederherstellbar) |
| DELETE | /api/automation/flows/{flowId}/draft | automation.manage | Den Entwurf verwerfen |
| POST | /api/automation/flows/{flowId}/restore | automation.manage | Einen gelöschten Flow wiederherstellen; er kommt ausgeschaltet zurück |
| POST | /api/automation/flows/{flowId}/resume | automation.manage | Einen pausierten Flow fortsetzen |
| POST | /api/automation/flows/{flowId}/detach | automation.manage | Den Flow einer Regel dauerhaft in einen normalen Flow umwandeln |
| GET | /api/automation/flows/{flowId}/versions | automation.read | Bereitgestellte Versionen, neueste zuerst, ohne Inhalt |
| GET | /api/automation/flows/{flowId}/versions/{version} | automation.read | Eine Version mit ihrem Inhalt |
| GET | /api/automation/flows/{flowId}/status | automation.read | Der Live-Status des laufenden Flows |
| POST | /api/automation/deploy | automation.manage | Flows und Operationen bereitstellen, alles oder nichts |
| POST | /api/automation/deploy/preflight | automation.manage | Was dieselbe Bereitstellung täte, ohne sie auszuführen |
| POST | /api/automation/test | automation.manage | Den gespeicherten Entwurf einmal als Testlauf ausführen |
| GET | /api/automation/debug/runs?flowId= | automation.read | Aufgezeichnete Läufe eines Flows |
| GET | /api/automation/debug/runs/{runId} | automation.read | Ein Lauf mit seinen Schritten |
| GET | /api/automation/flows/{flowId}/hooks | automation.read | Die Webhooks des Flows |
| POST | /api/automation/flows/{flowId}/hooks/{nodeId}/rotate | automation.manage | Ein neues Geheimnis für einen Webhook |
| GET | /api/automation/dlq | automation.read | Fehlgeschlagene Nachrichten |
| POST | /api/automation/dlq/{entryId}/replay | automation.manage | Eine fehlgeschlagene Nachricht erneut abspielen |
| DELETE | /api/automation/dlq/{entryId} | automation.manage | Eine fehlgeschlagene Nachricht verwerfen |
| GET | /api/automation/export?ids= | automation.manage | Bereitgestellte Flows als Datei exportieren |
| POST | /api/automation/import | automation.manage | Einen Import vorab prüfen und dann übernehmen |
| DELETE | /api/automation/import/{batchId} | automation.manage | Einen Import rückgängig machen |
| GET, POST | /api/automation/emergency-stop | Lesen: automation.read; ändern: automation.manage | Der Not-Aus |
| GET | /api/automation/hosts | automation.read | Die Hosts und ob Ihre Organisation sie nutzen darf |
| GET | /api/automation/blocks?host= | automation.read | Die auf einem Host verfügbaren Blöcke |
| GET | /api/automation/usage | automation.read | Lä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/flowsmithost,kind(flow),slug,name(bis zu 100 Zeichen), optionaldescriptionundtemplate. Antwortet mit201 { "flow" }. Ein bereits verwendeter Slug ergibt409 slug_taken. - Entwurf speichern:
PUT /api/automation/flows/{flowId}mit{ "draftRev": n, "draft": <content> }, wobeidraftRevdie 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.
| Feld | Bedeutung |
|---|---|
items | Zu 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. |
ops | Operationen: { "op": "enable", "flowId" }, disable, delete, { "op": "rollback", "flowId", "version" }, resume, set_root, unset_root |
confirm | Ihre 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}/replayantwortet mit{ "replayed": true, "entryId" };404 gone, wenn sie bereits wiederholt oder verworfen wurde,404 unreadable, wenn ihre Eingabe beschädigt ist,429 backpressuremitRetry-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/importmit{ "file", "choices": { "<slug>": "replace" }, "host": "generic" }.choicesist pro bereits vorhandenem Slugreplace,copyoderskip. Es wird nichts geschrieben; die Antwort{ "preview" }enthält, was sich ändern würde, die enthaltenen Bestätigungen und einpreviewToken, das 30 Minuten gültig ist. - Übernehmen: derselbe Body plus
previewToken. Antwort201 { "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 inskippedaufgefü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:
| Status | error | Bedeutung |
|---|---|---|
| 400 | bad_request | Die Anfrage ist nicht gültig. Ein Body, der die Feldregeln verletzt, ergibt Validation error mit issues. |
| 403 | forbidden | Ein 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 |
| 404 | not_found | „Flow not found.“ oder „Flow version not found.“ |
| 409 | conflict | Seit deinem Lesen wurde deployt oder gespeichert; die Deploy-Antwort enthält conflicts und current |
| 409 | in_use, slug_taken, owned_flow, not_owned | Wird noch von einem Root oder einem anderen Flow verwendet (uses); der Slug existiert; ein Flow einer Regel; kein Flow einer Regel |
| 410 | expired | „The flow was deleted too long ago to restore.“ |
| 413 | „The request body is too large.“ | |
| 422 | invalid | Der Flow lässt sich nicht kompilieren; problems listet jedes Problem auf |
| 428 | confirm | Bestätigungen fehlen; need listet sie auf |
| 503 | secrets_unavailable, owner_unavailable | Später erneut versuchen |
Den allgemeinen Fehler-Body und die Rate-Limits findest du unter Fehler und Rate-Limits.
Limits
| Limit | Wert |
|---|---|
| Blöcke und Operationen in einem Deploy | je 100 |
| Flow-Inhalt, Entwurf | je 1 MiB |
| Importdatei | 5 MiB |
| Deploy-Notiz | 500 Zeichen |
| Flow-Name, Beschreibung | 100, 1.000 Zeichen |
| Tests | 10 pro Minute und Mitglied; je 2 Sekunden und 200 Schritte |
| Läufe pro Listenseite | 100 |
| Fehlgeschlagene Nachrichten pro Listenseite | 200 |
| Gelöschten Flow wiederherstellen | Innerhalb von 7 Tagen |
| Altes Webhook-Geheimnis nach einer Rotation | 24 Stunden |
Plan-Limits und die Limits laufender Flows findest du unter Flow-Limits.

