Flows API

Create a new flow. Params: name (required), description. Returns empty flow ready for nodes.

List all automation flows. Returns array with id, name, description, isActive, triggerType, nodes[], edges[].

Get available node types for building flows. Params: type ("all"|"triggers"|"utilities"|"tools"|"connectors"|"agents"|"ai"), category, mcpServerId, connectorId, toolNames, search, limit (default 50), offset. Returns: triggers, utilities (with defaultConfig), ai config, tools (built-in apps, with inputSchema for each tool), connectors (the built-in Serenities tools first, then the user's own MCP connectors from Automations → Connectors, each with connectorId, slug and tools. Without toolNames / connectorId / category / search this is a COMPACT index — every tool's name, toolName, toolKind, group and one-line description, no inputSchema; pass toolNames: ["tables_createRow", …] to load exactly those tools with inputSchema, or narrow with connectorId / category / search for full detail, limit/offset paginated. Add one as a tool node with data.kind "connector" and data.connectorId, no connectionId; see nodeStructure.connectorStep), agents (the user's AI agents — add one as a tool node with data.kind "agent" and data.agentId, config {task, waitMode, timeoutMinutes}; see nodeStructure.agentStep), nodeStructure templates, utilityCategories.

Get flow details with nodes and edges. Param "id" is flow ID from list.

Update flow. Params: id (flow ID), name, description, isActive, triggerType, nodes, edges. Nodes: [{id, type: "trigger"|"tool"|"utility"|"ai", position: {x, y}, data: {label, sequenceNumber, ...}}]: a step's settings go in data.config; a trigger node has data.triggerType ("manual"|"webhook"|"schedule"|"table"|"event") and its own settings directly on data. A table trigger's settings sit directly on the node's data, never in data.config: data.triggerType "table", data.tableId (the table's id, from tables_listTables) and data.tableEventType, one of: row_created, row_updated, row_deleted, field_changed, status_changed, form_submitted, date_arrives, date_approaching, date_passed. Optional, also on data: viewId, fieldIds (field_changed, status_changed and the date_* events: the column), statusValues (status_changed) and daysBeforeApproaching (date_approaching). A connector step is a "tool" node with data.kind "connector" and data.connectorId (from getAvailableNodes type "connectors"); the connector must belong to the user or the save is refused. Trigger nodes have data.triggerType. Edges: [{id, source, target, sourceHandle: "output", targetHandle: "input"}]. After adding trigger nodes, use createWebhook/createSchedule to set up the backend.

Update a single node configuration in place (no need to resend the whole flow). Params: flowId, nodeId, config (object with node settings). REPLACES the node's existing config: read it with getById first and send the full merged object. The config shape of each node type comes from getAvailableNodes and getHelp; values support {{template}} references, e.g. {{#2.email}}. On a table trigger the settings (tableId, tableEventType, viewId, fieldIds, statusValues, daysBeforeApproaching) are written on the node's data, where the trigger reads them; any other key is refused. An Event Trigger is set with accountEvents_setFlowEventTrigger instead (refused here).

Edit node config by merging partial updates. Only provided fields are updated, existing fields preserved. Use this for adding mappings. Params: flowId, nodeId, config (partial object). On a table trigger the settings (tableId, tableEventType, viewId, fieldIds, statusValues, daysBeforeApproaching) are written on the node's data, where the trigger reads them; any other key is refused. An Event Trigger is set with accountEvents_setFlowEventTrigger instead (refused here).

Delete a flow. Param "id" is flow ID. WARNING: Permanent. Act only on what the person named or picked.

Create webhook trigger for a flow. Params: flowId, triggerId (trigger node ID). Returns webhook with token and URL.

Get webhook details. Params: flowId, triggerId (trigger node ID). Returns the live webhook link: treat it as a password (so this is a write tool that needs an edit role: a read-only connection or a Viewer is refused it).

Delete a flow's webhook trigger. Params: flowId, triggerId (trigger node ID). Act only on what the person named or picked.

Create a flow's schedule trigger. Params: flowId, triggerId (trigger node ID), cronExpression (5 parts: minute hour day month weekday), timezone (default UTC). Example: "0 9 * * *" for 9am daily.

Get a flow's schedule trigger. Param "triggerId" (trigger node ID).

Update a flow's schedule trigger. Params: triggerId, cronExpression, timezone.

Delete a flow's schedule trigger. Param "triggerId" (trigger node ID). Act only on what the person named or picked.

Get execution history for a flow with pagination. Params: flowId (required), limit (1-50, default 10), cursor (from previous response).

Get detailed execution info including node results. Params: executionId, includeFullData (boolean, for copying data).

Get the most recent running execution for a flow. Param "flowId".

Get all currently running executions for a flow. Param "flowId".

Get flow version history (snapshots). Each save creates a snapshot for rollback. Params: flowId, cursor (optional), limit (1-50, default 20).

Delete a snapshot. Cannot delete the latest snapshot. Param "snapshotId". Act only on what the person named or picked.

Restore flow nodes and edges from a previous snapshot. Params: flowId, snapshotId.

Stop a running execution. Param "executionId". Act only on what the person named or picked.

Execute a flow manually. Params: flowId (required), triggerData (optional object), triggerId (optional, uses manual trigger if not specified), executionMode ("test" (pinned data: steps that have pinned output use it) or "live" (live data: every step runs for real); only for this run. Triggered runs always do every step for real.). WHO RUNS IT: a flow runs as the workspace — whoever builds it decides what it can do and can only wire what they may use; anyone in the workspace can run it unless its "Who can run this flow" names who may (the Owner and Admins always can; its own triggers always start it). The person who started it is passed in as data: {{run.startedBy.name}}, {{run.startedBy.role}}, {{run.startedBy.kind}} — for personalising and logging, never rights.

Pin data to a node for testing: when the flow is in Pin mode, that step uses the pinned output instead of running. Pinned data is used only when you press Run here; every triggered run does every step for real. Params: flowId, nodeId, input (optional), output (required - the pinned data).

Remove pinned data from a node so it executes normally. Params: flowId, nodeId.

Toggle flow active/inactive. Param "flowId"; optional "expectActive" (whether it is on now, as you last saw it — if it changed since, nothing is changed). Inactive flows do not process webhook or schedule triggers.

Show the next real runs of a flow live in the editor; the flow still runs as usual. Params: flowId, triggerType ("webhook" or "table"), duration (ms, 1 second to 15 minutes, default 5 minutes).

Stop watching a flow's runs in the editor — for everyone in the workspace on that flow. Param "flowId".

Cancel a flow run that is still waiting for a free slot (it has not started yet): it is taken out of the waiting list and never starts. Param: executionId (the id the run was given when it was started). Anyone who may run the flow can cancel its waiting runs. A run that has already started, finished or been cancelled, or does not exist, answers that no waiting run was found; stop a running one with stopExecution. Returns { success: true, cancelled: true } when the run was taken out. Act only on what the person named or picked.

Get focused help for Flows API. Call when a parameter shape is unclear (one call per topic). Topics: - "overview": What flows are, quick start, node types - "nodes": Node structure, connecting nodes - "triggers": Manual, webhook, schedule triggers - "execution": Running flows, viewing history - "testing": Pinning data, test mode, listen mode Example: getHelp({topic: "triggers"}) before setting up webhooks.

Get the execute access rules for a flow (who may invoke it from a published app via flows.invoke), and hasHome (true when the flow already belongs to a site). Its home sites (`sites`) list only the sites you may open; saving the list keeps any you can't see. Param: id (flow ID).

Set who may invoke a flow from published apps via flows.invoke(). Flows are DENY-BY-DEFAULT — without rules only the owner can invoke. A flow a page starts runs as the workspace (it can read any of the owner's bases): only what its response node returns reaches the visitor. Params: id (flow ID), accessRules ({ execute: Condition, sites?: [siteId] } — same shape as backend-function rules). sites = the flow's HOME sites: only their members count for signed-in / role / plan / property rules, and through any other site the flow runs only if its rule says "Anyone, everywhere". Public has two levels: { type: "public", scope: "home" } = "Anyone on this site" (only through its home sites) and { type: "public", scope: "everywhere" } = "Anyone, everywhere". A public rule with no level keeps the saved one; made public now on a flow with home sites it starts as "Anyone on this site"; a flow with NO sites made public must name its sites or say scope "everywhere" — refused otherwise. Saving is checked like any flow save: you may only save rules you may change (refused if the flow holds something the person you act for may not use). Leaving `sites` out keeps the saved list.

"Who can run this flow" (teammates and agents, not site visitors): { everyone, roles, people, agents } — everyone: true when no list is set — and powers: what anyone who can run it can use it to do, in words. The Owner and Admins can always run it; its own triggers always start it. Param: flowId.

Set "Who can run this flow": everyone in the workspace (everyone: true), or the Owner, Admins and the roles (admin, editor = Developer, viewer), member user ids and agent ids you name. Running, stopping and raising an event that fires it follow the list; its own triggers always start it. Changing it is a save: refused if the flow holds something the person you act for may not use. Params: flowId, everyone, roles, people, agents.