Create a Workflow

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 for end-to-end examples of each pattern.

Authorization

API Key

x-api-key<token>

Authenticate using API Key in request header

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Unique name for the workflow. Must match ^[a-zA-Z0-9_-]{1,128}$.

Match^[a-zA-Z0-9_-]{1,128}$

Length1 <= length <= 128

displayName?string

Human-readable display name.

tags?array<>

Tags to categorize and organize the workflow.

mainNodeName*string

Name of the entry-point node. Must not be a destination of any edge.

nodes*array<>

Call-site nodes in the DAG. At least one is required.

Items1 <= items

edges?array<>

Directed edges between nodes. Omit or leave empty for single-node workflows.

connectors?array<>

Connectors to attach to the workflow at creation. If any entry fails to provision, the entire workflow creation is rolled back.

Response Body

`application/json`

curl -X POST "https://api.bem.ai/v3/workflows" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "mainNodeName": "string",    "nodes": [      {        "function": {}      }    ]  }'

{
  "workflow": {
    "id": "string",
    "name": "string",
    "versionNum": 0,
    "displayName": "string",
    "emailAddress": "string",
    "tags": [
      "string"
    ],
    "mainNodeName": "string",
    "nodes": [
      {
        "name": "string",
        "function": {
          "id": "string",
          "name": "string",
          "versionNum": 0
        },
        "metadata": {}
      }
    ],
    "edges": [
      {
        "sourceNodeName": "string",
        "destinationName": "string",
        "destinationNodeName": "string",
        "metadata": {}
      }
    ],
    "connectors": [
      {
        "connectorID": "string",
        "name": "string",
        "type": "paragon",
        "paragon": {
          "integration": "string",
          "configuration": {},
          "syncID": "string"
        }
      }
    ],
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z",
    "audit": {
      "workflowCreatedBy": {
        "userActionID": "string",
        "userID": "string",
        "userEmail": "string",
        "apiKeyName": "string",
        "emailAddress": "string",
        "createdAt": "2019-08-24T14:15:22Z"
      },
      "workflowLastUpdatedBy": {
        "userActionID": "string",
        "userID": "string",
        "userEmail": "string",
        "apiKeyName": "string",
        "emailAddress": "string",
        "createdAt": "2019-08-24T14:15:22Z"
      },
      "versionCreatedBy": {
        "userActionID": "string",
        "userID": "string",
        "userEmail": "string",
        "apiKeyName": "string",
        "emailAddress": "string",
        "createdAt": "2019-08-24T14:15:22Z"
      }
    }
  },
  "error": "string",
  "connectorErrors": [
    {
      "connectorID": "string",
      "name": "string",
      "operation": "create",
      "message": "string",
      "code": "string"
    }
  ]
}