New: the AI firewall watches the whole platform and explains each incident in plain words. See how it works

Flows API

Create, save, deploy, test, roll back, restore and export flows over REST, read their runs and webhooks, and replay failed messages.

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

PermissionDefault roleAllows
automation.readAdminRead flows, versions, runs without message contents, failed messages without their input, webhooks, usage
automation.manageAdminCreate, save, deploy, delete, restore, test, import and export flows; replay and discard failed messages
automation.manage_privilegedAdminDeploy flows with control-level blocks
automation.debugAdminSee 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

MethodPathPermissionDoes
GET/api/automation/flowsautomation.readList flows
POST/api/automation/flowsautomation.manageCreate a flow as a first draft (never deployed, off)
GET/api/automation/flows/{flowId}automation.readThe flow, its deployed content and its shared draft
PUT/api/automation/flows/{flowId}automation.manageSave the shared draft
PATCH/api/automation/flows/{flowId}automation.manageChange the description
DELETE/api/automation/flows/{flowId}automation.manageDelete (restorable for 7 days)
DELETE/api/automation/flows/{flowId}/draftautomation.manageDiscard the draft
POST/api/automation/flows/{flowId}/restoreautomation.manageRestore a deleted flow; it comes back switched off
POST/api/automation/flows/{flowId}/resumeautomation.manageResume a paused flow
POST/api/automation/flows/{flowId}/detachautomation.manageTurn a rule’s flow into an ordinary flow, for good
GET/api/automation/flows/{flowId}/versionsautomation.readDeployed versions, newest first, without content
GET/api/automation/flows/{flowId}/versions/{version}automation.readOne version with its content
GET/api/automation/flows/{flowId}/statusautomation.readThe live status of the running flow
POST/api/automation/deployautomation.manageDeploy flows and operations, all or nothing
POST/api/automation/deploy/preflightautomation.manageWhat the same deploy would do, without doing it
POST/api/automation/testautomation.manageRun the saved draft once as a dry run
GET/api/automation/debug/runs?flowId=automation.readRecorded runs of a flow
GET/api/automation/debug/runs/{runId}automation.readOne run with its steps
GET/api/automation/flows/{flowId}/hooksautomation.readThe flow’s webhooks
POST/api/automation/flows/{flowId}/hooks/{nodeId}/rotateautomation.manageA new secret for one webhook
GET/api/automation/dlqautomation.readFailed messages
POST/api/automation/dlq/{entryId}/replayautomation.manageReplay one failed message
DELETE/api/automation/dlq/{entryId}automation.manageDiscard one failed message
GET/api/automation/export?ids=automation.manageExport deployed flows as a file
POST/api/automation/importautomation.managePreview, then commit, an import
DELETE/api/automation/import/{batchId}automation.manageUndo an import
GET, POST/api/automation/emergency-stopread: automation.read; change: automation.manageThe emergency stop
GET/api/automation/hostsautomation.readThe hosts and whether your organisation may use them
GET/api/automation/blocks?host=automation.readThe blocks available on a host
GET/api/automation/usageautomation.readThis 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/flows with host, kind (flow), slug, name (up to 100 characters), optional description and template. Answers 201 { "flow" }. A slug in use is 409 slug_taken.
  • Save the draft: PUT /api/automation/flows/{flowId} with { "draftRev": n, "draft": <content> }, where draftRev is 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.

FieldMeaning
itemsFlows 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.
opsOperations: { "op": "enable", "flowId" }, disable, delete, { "op": "rollback", "flowId", "version" }, resume, set_root, unset_root
confirmYour 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}/replay answers { "replayed": true, "entryId" }; 404 gone when it was replayed or discarded already, 404 unreadable when its input is damaged, 429 backpressure with Retry-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/import with { "file", "choices": { "<slug>": "replace" }, "host": "generic" }. choices is replace, copy or skip per slug that already exists. Nothing is written; the answer { "preview" } holds what would change, the confirmations it carries and a previewToken, valid 30 minutes.
  • Commit: the same body plus previewToken. Answers 201 { "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=true to see the plan). A flow deployed since the import is left alone and listed in skipped.

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:

StatuserrorMeaning
400bad_requestThe request is not valid. A body that breaks the field rules is Validation error with issues.
403forbiddenA 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
404not_found“Flow not found.” or “Flow version not found.”
409conflictSomeone deployed or saved since you read; the deploy answer holds conflicts and current
409in_use, slug_taken, owned_flow, not_ownedStill used by a root or another flow (uses); the slug exists; a rule’s flow; not a rule’s flow
410expired“The flow was deleted too long ago to restore.”
413“The request body is too large.”
422invalidThe flow does not compile; problems lists each
428confirmConfirmations are missing; need lists them
503secrets_unavailable, owner_unavailableTry again later

See Errors and rate limits for the general error body and rate limits.

Limits

LimitValue
Items and ops in one deploy100 each
Flow content, draft1 MiB each
Import file5 MiB
Deploy note500 characters
Flow name, description100, 1,000 characters
Tests10 a minute per member; 2 seconds and 200 steps each
Runs per list page100
Failed messages per list page200
Restore a deleted flowWithin 7 days
Old webhook secret after a rotation24 hours

Plan limits and the limits of running flows are on Flow limits.