--- title: "Create a Workflow" method: POST path: "/v3/workflows" tags: ["Workflows"] --- # Create a Workflow `POST /v3/workflows` **Create a workflow.** A workflow is a directed acyclic graph of nodes (each pointing at a function) with one entry point (`mainNodeName`). The graph runs end-to-end on every call. ## Required structure - `name`: unique within the environment, alphanumeric plus hyphens and underscores. - `mainNodeName`: must match one of the `nodes[].name` values, and must not be the destination of any edge. - `nodes`: at least one. Each node has a unique `name` and a `function` reference (by `functionName` or `functionID`, optionally pinned to a `versionNum`). - `edges`: optional for single-node workflows. For branching sources (Classify, semantic Split), each edge carries a `destinationName` matching a `classifications[].name` or `itemClasses[].name` on the source function. The created workflow is at `versionNum: 1`. Subsequent `PATCH /v3/workflows/{workflowName}` calls produce new versions. ## Common patterns - **Single-node**: one extract/classify function, no edges. - **Sequential**: extract → enrich → payload_shaping (linear edges). - **Branching**: classify → multiple extracts (one edge per classification name). - **Split-then-process**: split → multiple extracts (one edge per item class). See [Workflows explained](/guide/workflows-explained) for end-to-end examples of each pattern. ## Request body - WorkflowCreateRequestV3 - `name` string, required — Unique name for the workflow. 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, required — Name of the entry-point node. Must not be a destination of any edge. - `nodes` WorkflowNodeRequest[], required — Call-site nodes in the DAG. At least one is required. - `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[] — Directed edges between nodes. Omit or leave empty for single-node workflows. - `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[] — Connectors to attach to the workflow at creation. If any entry fails to provision, the entire workflow creation is rolled back. - `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. - WorkflowV3CreateResponse - `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 creation 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 > 42 revisions in range; 1 could not be searched. - **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/post.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)