--- 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. - `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 - **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/643398900e5d/schema)