--- title: "Update a Workflow" method: PATCH path: "/v3/workflows/{workflowName}" tags: ["Workflows"] --- # Update a Workflow `PATCH /v3/workflows/{workflowName}` **Update a workflow. Updates create a new version.** The previous version remains addressable and immutable. Pending and running calls captured at the old version continue against it; new calls run against the new version. ## Topology updates To change the graph you must provide `mainNodeName`, `nodes`, AND `edges` together — partial topology updates are rejected. The full graph is replaced atomically. ## Metadata-only updates Omit all three fields to update only `displayName`, `tags`, or `name` while keeping the topology of the current version. ## Reverting To roll back, fetch the desired prior version and resubmit its `mainNodeName`/`nodes`/`edges` as a new update. Versions themselves are immutable — there is no "pin to version N" operation at the workflow level (use `nodes[].function.versionNum` to pin individual functions). ## Path parameters - `workflowName` string, required ## Request body - WorkflowUpdateRequestV3 - `name` string — New name for the workflow (renames it). Must match `^[a-zA-Z0-9_-]{1,128}$`. - `displayName` string — Human-readable display name. - `tags` string[] — Tags to categorize and organize the workflow. - `mainNodeName` string — `mainNodeName`, `nodes`, and `edges` must be provided together to update the DAG topology. If none are provided the topology is copied unchanged from the current version. - `nodes` WorkflowNodeRequest[] - `name` string — Name for this call site. Must be unique within the workflow version. Defaults to the function's own name when omitted. - `function` FunctionVersionIdentifier, required - `id` string — Unique identifier of function. Provide either id or name, not both. - `name` string — Name of function. Must be UNIQUE on a per-environment basis. Provide either id or name, not both. - `versionNum` integer — Version number of function. - `metadata` object — Opaque free-form JSON object attached to this node. Stored and returned verbatim; the server does not interpret it. Intended for client-side concerns such as canvas display properties (position, color, collapsed state, etc.). - `edges` WorkflowEdgeRequest[] - `sourceNodeName` string, required — Name of the source node. - `destinationName` string — Labelled outlet on the source node that activates this edge. Omit for the default (unlabelled) outlet. - `destinationNodeName` string, required — Name of the destination node. - `metadata` object — Opaque free-form JSON object attached to this edge. Stored and returned verbatim; the server does not interpret it. - `connectors` WorkflowConnectorRequest[] — Declarative, full-desired-state array of connectors. If omitted, existing connectors are left unchanged. If provided, it replaces the current set: entries with `connectorID` are updates, entries without are creates, and existing connectors whose `connectorID` is absent are deleted. - `connectorID` string — Present → update. Absent → create. - `name` string, required — Human-friendly connector name. - `type` 'paragon', required — Discriminator for a workflow connector. V3 supports `paragon` only. - `paragon` ParagonConnectorRequestConfig — Request-side config block for a Paragon connector. Fields absent on update are unchanged. - `integration` string — Paragon integration key. Required on create. - `configuration` object — Opaque per-integration configuration. Required on create. ## Response `200` The request has succeeded. - WorkflowV3UpdateResponse - `workflow` WorkflowV3 — V3 read representation of a workflow version. - `id` string, required — Unique identifier of the workflow. - `name` string, required — Unique name of the workflow within the environment. - `versionNum` integer, required — Version number of this workflow version. - `displayName` string — Human-readable display name. - `emailAddress` string — Inbound email address associated with the workflow, if any. - `tags` string[] — Tags associated with the workflow. - `mainNodeName` string, required — Name of the entry-point call-site node. - `nodes` WorkflowNodeResponse[], required — All call-site nodes in this workflow version's DAG. - `name` string, required — Name of this call site, unique within the workflow version. - `function` FunctionVersionIdentifier, required - `id` string — Unique identifier of function. Provide either id or name, not both. - `name` string — Name of function. Must be UNIQUE on a per-environment basis. Provide either id or name, not both. - `versionNum` integer — Version number of function. - `metadata` object — Opaque free-form JSON object attached to this node on create/update. Returned verbatim; never interpreted by the server. - `edges` WorkflowEdgeResponse[], required — All directed edges in this workflow version's DAG. - `sourceNodeName` string, required — Name of the source node. - `destinationName` string — Labelled outlet on the source node, if any. - `destinationNodeName` string, required — Name of the destination node. - `metadata` object — Opaque free-form JSON object attached to this edge on create/update. Returned verbatim; never interpreted by the server. - `connectors` WorkflowConnector[], required — Connectors currently attached to this workflow. For version-scoped reads (`/versions/{n}`) this is always empty — connectors are current-state and not part of version history. - `connectorID` string, required — Unique connector API ID. - `name` string, required — Human-friendly connector name. - `type` 'paragon', required — Discriminator for a workflow connector. V3 supports `paragon` only. - `paragon` ParagonConnectorConfig — Paragon-integration configuration on a workflow connector. - `integration` string, required — Paragon integration key (e.g. "googledrive"). - `configuration` object, required — Opaque per-integration configuration (e.g. `{"folderId": "..."}`). - `syncID` string, required — Paragon sync ID managed by the server. Read-only. - `createdAt` string, date-time, required — The date and time the workflow was created. - `updatedAt` string, date-time, required — The date and time the workflow was last updated. - `audit` WorkflowAudit - `workflowCreatedBy` UserActionSummary - `userActionID` string, required — Unique identifier of the user action. - `userID` string — User's ID. Present for user-initiated actions. - `userEmail` string — User's email address. Present for user-initiated actions. - `apiKeyName` string — API key name. Present for API key-initiated actions. - `emailAddress` string — Email address. Present for email-initiated actions. - `createdAt` string, date-time, required — The date and time the action was created. - `workflowLastUpdatedBy` UserActionSummary - `userActionID` string, required — Unique identifier of the user action. - `userID` string — User's ID. Present for user-initiated actions. - `userEmail` string — User's email address. Present for user-initiated actions. - `apiKeyName` string — API key name. Present for API key-initiated actions. - `emailAddress` string — Email address. Present for email-initiated actions. - `createdAt` string, date-time, required — The date and time the action was created. - `versionCreatedBy` UserActionSummary - `userActionID` string, required — Unique identifier of the user action. - `userID` string — User's ID. Present for user-initiated actions. - `userEmail` string — User's email address. Present for user-initiated actions. - `apiKeyName` string — API key name. Present for API key-initiated actions. - `emailAddress` string — Email address. Present for email-initiated actions. - `createdAt` string, date-time, required — The date and time the action was created. - `restricted` boolean, required — Whether this workflow is hidden from other members of the account in the bem web app. When true, only account owners and admins and explicitly granted users see the workflow and its calls, outputs, and errors in the app. This is a UI-visibility control: API keys are not scoped to workflows, so an environment API key still reads a restricted workflow and its data. - `error` string — Error message if the workflow update failed. - `connectorErrors` WorkflowConnectorError[] — Per-connector failures from the diff/apply phase. Empty or omitted when all operations succeeded. - `connectorID` string — Populated for update/delete failures. - `name` string — Populated for create failures. - `operation` 'create' | 'update' | 'delete', required — Which diff operation was attempted. - `message` string, required — Human-readable error message. - `code` string, required — Machine-readable error code. ## Changes - **2026-08-05** `e3a4c8c54d97` — 1 info - added the required property `workflow/restricted` to the response with the `200` status - **2026-04-17** `9755ec390110` — 7 info - added the new optional request property `connectors` - added the new optional request property `edges/items/metadata` - added the new optional request property `nodes/items/metadata` - added the optional property `connectorErrors` to the response with the `200` status - …3 more [Change history](https://skmtc.dev/bem-team/apis/bem-api/changes/v3/workflows/:workflowName/patch.md) --- [API](https://skmtc.dev/bem-team/apis/bem-api.md) · [All operations](https://skmtc.dev/bem-team/apis/bem-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/bem-team/bem-api/revisions/a6e4624117c6/schema)