---
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.
  - `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.

---

[API](https://skmtc.net/bem-team/apis/bem-api.md) · [All operations](https://skmtc.net/bem-team/apis/bem-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bem-team/bem-api/versions/b0a6debb3458/schema)