These routes let a program work with the flows of the automation engine: keep flows in version control and deploy them, roll back, watch runs and handle failed messages. How flows work in the app is explained in Flows and Versions, testing and rollback.
Paths are under https://<your host>/tenant/<tenantId>. Send Authorization: Bearer <API key> on every call; see Authentication. Times in this API are milliseconds since the epoch.
Permissions and API keys
| Permission | Default role | Allows |
|---|---|---|
automation.read | Admin | Read flows, versions, runs without message contents, failed messages without their input, webhooks, usage |
automation.manage | Admin | Create, save, deploy, delete, restore, test, import and export flows; replay and discard failed messages |
automation.manage_privileged | Admin | Deploy flows with control-level blocks |
automation.debug | Admin | See message contents in runs and failed messages; test from recorded messages and live state |
An API key can hold all four. A deploy also asks for the permissions the flow’s blocks need: a Send command block needs the send permission of the command’s tier (iot_rpc.send.basic, iot_rpc.send.privileged, iot_rpc.send.critical), and automation.manage_privileged when the command is high impact. A raw command method needs iot_rpc.send.raw, which only an Owner holds and no key can, so a key cannot deploy a flow that sends raw methods.
A flow belongs to a host: generic (the General host) or iot (the IoT host). See Hosts, the root flow and profile root flows.
Routes
| Method | Path | Permission | Does |
|---|---|---|---|
| GET | /api/automation/flows | automation.read | List flows |
| POST | /api/automation/flows | automation.manage | Create a flow as a first draft (never deployed, off) |
| GET | /api/automation/flows/{flowId} | automation.read | The flow, its deployed content and its shared draft |
| PUT | /api/automation/flows/{flowId} | automation.manage | Save the shared draft |
| PATCH | /api/automation/flows/{flowId} | automation.manage | Change the description |
| DELETE | /api/automation/flows/{flowId} | automation.manage | Delete (restorable for 7 days) |
| DELETE | /api/automation/flows/{flowId}/draft | automation.manage | Discard the draft |
| POST | /api/automation/flows/{flowId}/restore | automation.manage | Restore a deleted flow; it comes back switched off |
| POST | /api/automation/flows/{flowId}/resume | automation.manage | Resume a paused flow |
| POST | /api/automation/flows/{flowId}/detach | automation.manage | Turn a rule’s flow into an ordinary flow, for good |
| GET | /api/automation/flows/{flowId}/versions | automation.read | Deployed versions, newest first, without content |
| GET | /api/automation/flows/{flowId}/versions/{version} | automation.read | One version with its content |
| GET | /api/automation/flows/{flowId}/status | automation.read | The live status of the running flow |
| POST | /api/automation/deploy | automation.manage | Deploy flows and operations, all or nothing |
| POST | /api/automation/deploy/preflight | automation.manage | What the same deploy would do, without doing it |
| POST | /api/automation/test | automation.manage | Run the saved draft once as a dry run |
| GET | /api/automation/debug/runs?flowId= | automation.read | Recorded runs of a flow |
| GET | /api/automation/debug/runs/{runId} | automation.read | One run with its steps |
| GET | /api/automation/flows/{flowId}/hooks | automation.read | The flow’s webhooks |
| POST | /api/automation/flows/{flowId}/hooks/{nodeId}/rotate | automation.manage | A new secret for one webhook |
| GET | /api/automation/dlq | automation.read | Failed messages |
| POST | /api/automation/dlq/{entryId}/replay | automation.manage | Replay one failed message |
| DELETE | /api/automation/dlq/{entryId} | automation.manage | Discard one failed message |
| GET | /api/automation/export?ids= | automation.manage | Export deployed flows as a file |
| POST | /api/automation/import | automation.manage | Preview, then commit, an import |
| DELETE | /api/automation/import/{batchId} | automation.manage | Undo an import |
| GET, POST | /api/automation/emergency-stop | read: automation.read; change: automation.manage | The emergency stop |
| GET | /api/automation/hosts | automation.read | The hosts and whether your organisation may use them |
| GET | /api/automation/blocks?host= | automation.read | The blocks available on a host |
| GET | /api/automation/usage | automation.read | This month’s runs, steps and script time, and flows against your plan |
List and read flows
GET /api/automation/flows pages from 1, 50 rows by default, at most 100. Filters: host, kind, state (comma lists; states are running, disabled, invalid, not_approved, paused), enabled, owned (true for rule flows, false for ordinary ones), updatedFrom / updatedTo (days), search, deleted=true (the deleted flows of the last 7 days), ids. Sort fields: name, slug, host, kind, state, enabled, version, updatedAt, createdAt, deletedAt, sortOrder. The answer is { "flows": [...], "data": [...], "total": n, "page": 1, "pageSize": 50 }; data holds the same rows.
A flow row has flowId, host, slug (the flow’s fixed id, ^[a-z0-9_-]{1,32}$), name, description, enabled, state, stateReason, version (the deployed version, 0 before the first deploy), draftRev, deletedAt, createdAt, updatedAt, and ownerModule for a flow the Rules card owns.
GET /api/automation/flows/{flowId} answers { "flow", "current", "draft", "permissions" }: current is the deployed version with its content, draft the shared draft, and permissions which of automation.manage, automation.manage_privileged and automation.debug the caller holds.
Content, drafts and creating a flow
Flow content is { "id": "<slug>", "name": "…", "nodes": [...], "edges": [...] }. A node is { "id", "type", "params", "name"?, "disabled"? }; an edge is { "from", "from_port", "to" }. The block types and their parameters are listed by GET /api/automation/blocks?host=generic and described from Trigger blocks on. The easiest way to get valid content is to build a flow in the editor and read it with GET /api/automation/flows/{flowId}.
- Create:
POST /api/automation/flowswithhost,kind(flow),slug,name(up to 100 characters), optionaldescriptionandtemplate. Answers201 { "flow" }. A slug in use is409 slug_taken. - Save the draft:
PUT /api/automation/flows/{flowId}with{ "draftRev": n, "draft": <content> }, wheredraftRevis the revision you read. Answers{ "draftRev" }with the new revision; send it with your next save. If someone saved in between:409 { "error": "conflict", "draftRev", "by", "at", "theirs" }. A draft never runs.
Deploy
POST /api/automation/deploy deploys any number of flows and operations at once, all or nothing.
| Field | Meaning |
|---|---|
items | Flows to deploy: host, kind, content, enabled, optional note (up to 500 characters). For an existing flow, flowId and baseVersion (the version you read; 0 if it was never deployed). Without flowId a new flow is created. |
ops | Operations: { "op": "enable", "flowId" }, disable, delete, { "op": "rollback", "flowId", "version" }, resume, set_root, unset_root |
confirm | Your confirmations, by flow slug: { "<slug>": { "check": true } } or { "<slug>": { "typed": "<flow name>" } } |
Up to 100 items and 100 ops; each flow’s content at most 1 MiB. Send enabled explicitly on each item.
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":[]}}]}'
The answer is { "deployRev", "versions": [ { "flowId", "slug", "kind", "version", "approved" } ], "plan", "dropped", "warnings"?, "notified" }. notified: false means the change is saved and the workers pick it up within a minute.
Confirmations
A flow with risky blocks must be confirmed, as in the editor’s deploy dialog. Without the confirmation the deploy answers 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" } ] }
Send the same body again with confirm: { "check": true } for level check, or { "typed": "Tank alert" } (the flow’s name, exactly) for level typed. An approval carries over to the next deploy of the same content by the same member, so redeploying unchanged content asks nothing.
Use POST /api/automation/deploy/preflight with the same body to see the answer without deploying: nothing is written, locked or audited.
Versions and rollback
GET .../versions answers { "versions": [ { "version", "at", "by", "note", "mode", "hashShort", "approvedBy" } ] }. To roll back, deploy { "ops": [ { "op": "rollback", "flowId": "9e8f…", "version": 3 } ] }. A rollback is a new version with the old content and needs the same permissions and confirmations. How long versions are kept is on Versions, testing and rollback.
Test the draft
POST /api/automation/test runs the saved draft once, as a dry run: blocks that act outside say what they would do, and nothing is written or sent.
{ "flowId": "9e8f…", "mode": "flow", "nodeId": "trigger-1", "input": { "msgType": "inject", "payload": { "level": 92 }, "originator": { "type": "tenant", "id": "<tenantId>" } } }
mode is flow (enter through the trigger nodeId) or node (run only nodeId). Instead of a message, input can be { "sample": "declaration" } (the block’s sample) or, with automation.debug, { "sample": "last_run" } or { "fromRun": { "runId", "step" } }. The answer has steps, outputs, would, errors, ms, truncated and state. A test stops after 2 seconds or 200 steps. Each member may run 10 tests a minute: then 429 rate_limited with Retry-After.
Runs and status
GET /api/automation/debug/runs?flowId=<flowId or slug> lists recorded runs, newest first. Filters: nodeId, status (ok, error, left_open, dropped), msgType, originatorType, originatorId, port, from and to (milliseconds), limit (at most 100), and cursor (the next of the previous page). Without automation.debug the rows come without message contents. Only what the flow’s recording level keeps is listed; see Troubleshooting flows. A third scan at the same time in your organisation answers 429.
GET /api/automation/flows/{flowId}/status answers { "status" }: node status lines, counters, rate and queue as the running flow last reported them, or null before the first report. The editor’s live stream is for signed-in people only; a program polls this route instead.
Webhooks
GET /api/automation/flows/{flowId}/hooks lists the webhook triggers of a deployed, switched-on flow: { "hooks": [ { "nodeId", "hookId", "auth", "reply", "path" } ] }. The answer never holds a secret.
POST .../hooks/{nodeId}/rotate makes a new secret and shows it once: { "hookId", "secret", "previousValidHours": 24 }. The old secret keeps working for 24 hours; send { "revokePrevious": true } to end it at once. A session webhook has no secret (409 no_secret).
A program that calls a webhook does not use an API key: it uses the hook’s own secret, as described under Webhook in Trigger blocks.
Failed messages
GET /api/automation/dlq lists failed messages, newest first, pageSize up to 200 (default 50). For the next page pass next as before (or as after when you sort firstSeenAt:asc); next is null at the end of the queue. Filters: reason (tenant_backlog, decode_failed, poison, host_refused, run_abandoned, retries_exhausted, expired), flow (a slug), host (default generic). The answer has total, byReason (counted over the newest 900), entries and next. Each entry has id, reason, error, firstSeenAt, deliveries and, with automation.debug, the original input in fields.
POST /api/automation/dlq/{entryId}/replayanswers{ "replayed": true, "entryId" };404 gonewhen it was replayed or discarded already,404 unreadablewhen its input is damaged,429 backpressurewithRetry-After: 30.DELETE /api/automation/dlq/{entryId}answers{ "discarded": true }.
Add ?host=iot for the IoT host’s queue. A replay can repeat work the first attempt did; see Protections and failed messages.
Export and import
- Export:
GET /api/automation/export?ids=<flowId>,<flowId>(1 to 100) answers{ "file", "skipped" }with the deployed version of each flow and the connections it uses. Secrets are never in the file. - Preview an import:
POST /api/automation/importwith{ "file", "choices": { "<slug>": "replace" }, "host": "generic" }.choicesisreplace,copyorskipper slug that already exists. Nothing is written; the answer{ "preview" }holds what would change, the confirmations it carries and apreviewToken, valid 30 minutes. - Commit: the same body plus
previewToken. Answers201 { "imported": { "importBatchId", … } }. Imported flows arrive switched off and not approved; enter their secrets again, then deploy them on. - Undo:
DELETE /api/automation/import/{importBatchId}(?dryRun=trueto see the plan). A flow deployed since the import is left alone and listed inskipped.
The file may be at most 5 MiB. A commit answers 409 stale_preview when something was deployed since the preview, 409 preview_expired after 30 minutes and 409 token_mismatch when the token does not match the body. Preview again in each case.
Flows of Rules card rules
A rule of the Rules card runs as a flow that the flow API lists with ownerModule. Saving, deploying, deleting or replacing it answers 409 owned_flow: change the rule through the Rules API instead. POST .../detach turns it into an ordinary flow for good: the rule is deleted, and the flow then counts against your plan’s flow limit.
Errors
Refusals of the automation routes carry an error code beside the usual fields:
| Status | error | Meaning |
|---|---|---|
| 400 | bad_request | The request is not valid. A body that breaks the field rules is Validation error with issues. |
| 403 | forbidden | A block of the flow needs a permission the key does not hold (missing) |
| 403 | (none) | A plan limit: details.key max_flows or max_script_blocks, with limit, current, adding |
| 404 | not_found | “Flow not found.” or “Flow version not found.” |
| 409 | conflict | Someone deployed or saved since you read; the deploy answer holds conflicts and current |
| 409 | in_use, slug_taken, owned_flow, not_owned | Still used by a root or another flow (uses); the slug exists; a rule’s flow; not a rule’s flow |
| 410 | expired | “The flow was deleted too long ago to restore.” |
| 413 | “The request body is too large.” | |
| 422 | invalid | The flow does not compile; problems lists each |
| 428 | confirm | Confirmations are missing; need lists them |
| 503 | secrets_unavailable, owner_unavailable | Try again later |
See Errors and rate limits for the general error body and rate limits.
Limits
| Limit | Value |
|---|---|
| Items and ops in one deploy | 100 each |
| Flow content, draft | 1 MiB each |
| Import file | 5 MiB |
| Deploy note | 500 characters |
| Flow name, description | 100, 1,000 characters |
| Tests | 10 a minute per member; 2 seconds and 200 steps each |
| Runs per list page | 100 |
| Failed messages per list page | 200 |
| Restore a deleted flow | Within 7 days |
| Old webhook secret after a rotation | 24 hours |
Plan limits and the limits of running flows are on Flow limits.

