> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lyzr.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow Definition (flow_data)

> The structure of the flow_data document accepted by the SuperFlow workflow endpoints, including nodes, connections, and expression syntax.

`flow_data` is the JSON document that defines a SuperFlow workflow graph. The workflow endpoints accept it in three places: [Create Workflow](/enterprise/api/superflow/workflows/create), [Update Workflow](/enterprise/api/superflow/workflows/update), and inline in [Execute Workflow](/enterprise/api/superflow/executions/execute). This page describes the envelope, the node object, connections, and the expression syntax. The full catalog of node types lives in the [node types reference](/enterprise/api/superflow/node-types).

<Note>
  If you build workflows in the Studio editor, you rarely need this page. It exists for callers who construct or modify `flow_data` programmatically. For a task-oriented walkthrough of the same concepts in the UI, see the [SuperFlow node reference](/enterprise/agent-studio/superflow/node-reference).
</Note>

## Envelope

`flow_data` is a JSON object describing a directed graph of nodes. The engine recognizes the following top-level keys and ignores any others.

| Key           | Type                                  | Required | Description                                                                                    |
| ------------- | ------------------------------------- | -------- | ---------------------------------------------------------------------------------------------- |
| `name`        | string                                | No       | Workflow name.                                                                                 |
| `nodes`       | array of [node objects](#node-object) | Yes      | The workflow's nodes. Must be non-empty.                                                       |
| `connections` | object keyed by source node name      | No       | Directed edges between nodes. See [Connections and error edges](#connections-and-error-edges). |
| `settings`    | object                                | No       | Workflow-level settings.                                                                       |

The engine validates the document on submission. The `nodes` array must be non-empty, and there must be exactly one node of type `lyzr-nodes-base.trigger`; zero trigger nodes or more than one is an error. Connections whose source name does not match a real node are ignored, as are connection targets that are empty or reference a non-existent node.

## Node object

Each entry in `nodes` is an object with the following keys.

| Key           | Type         | Required | Description                                                                                                                                 |
| ------------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`          | string       | Yes      | Unique node ID.                                                                                                                             |
| `name`        | string       | Yes      | Human-readable name. This value, not `id`, is used as the key in `connections`.                                                             |
| `type`        | string       | Yes      | Node type, one of the types in the [node types reference](/enterprise/api/superflow/node-types). All types are prefixed `lyzr-nodes-base.`. |
| `typeVersion` | number       | Yes      | Node type version. Fractional versions such as 1.8, 2.1, and 4.2 are allowed.                                                               |
| `parameters`  | object       | Yes      | Node configuration, documented per node type. String values may contain `{{ }}` expressions.                                                |
| `credentials` | object       | No       | Inline node credentials, for example `<provider>Api.apiKey`.                                                                                |
| `settings`    | object       | No       | Per-node settings such as `retryOnFail`, `continueOnFail`, and `handleErrors`.                                                              |
| `position`    | number array | Yes      | Editor coordinates as a two-element `[x, y]` array.                                                                                         |

## Connections and error edges

`connections` is keyed by the source node's `name`, not its `id`. Each value is an object with two optional keys, `main` for the success path and `error` for the failure path. Both keys have the same shape: an array of output slots, where slot `i` (for example `main[i]`) is itself an array of target objects. The slot index is the source node's output index.

Each target object has three keys.

| Key     | Type    | Description                                |
| ------- | ------- | ------------------------------------------ |
| `node`  | string  | Target node name.                          |
| `type`  | string  | Connection type label, typically `"main"`. |
| `index` | integer | Target input index.                        |

When a node has `settings.handleErrors` set to `true` and fails permanently, downstream execution follows its `error` edges instead of aborting the run. Without `handleErrors`, a permanent failure aborts the run. `error` slots use the identical nested shape as `main`.

```json theme={null}
"connections": {
  "HTTP Request": {
    "main":  [[ { "node": "Set",           "type": "main", "index": 0 } ]],
    "error": [[ { "node": "Error Handler",  "type": "main", "index": 0 } ]]
  }
}
```

## Expression syntax

Before a node runs, its `parameters` are resolved recursively. For every string value at any depth, including strings nested in objects and arrays, the engine first strips a single leading `=` (the expression-mode prefix, as in `"={{ $json.x }}"`), then resolves every `{{ ... }}` block.

If the whole string after the `=` prefix is exactly one `{{ ... }}` block, the resolved value keeps its native type (number, boolean, object, or array). Otherwise each block is interpolated into the surrounding string: primitives become text, and objects and arrays are JSON-encoded. The practical consequence is that every string parameter on every node supports expressions.

The following forms are supported inside `{{ }}`.

| Form                                          | Meaning                                                                                                        |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `$json`                                       | The current node's first input item as a whole object.                                                         |
| `$json.a.b.c`                                 | A dot-path into the first input item.                                                                          |
| `$input.item.json` and `$input.item.json.a.b` | Aliases for `$json` and `$json.a.b`.                                                                           |
| `$node["Name"].json.field`                    | A field from a named node's first output item. Single or double quotes are accepted.                           |
| `$node["Name"].json` and `$node["Name"]`      | The named node's entire first output item.                                                                     |
| `$('Name').json.field`                        | Shorthand for `$node["Name"]`. An `.item` segment, as in `$('Name').item.json.field`, is accepted and ignored. |
| `$('Name').json` and `$('Name')`              | The named node's entire first output item.                                                                     |

Dot-paths traverse object keys and array indices, for example `results.0.name`. A missing key or an out-of-range index yields `null`.

A bare reference such as `$json.x`, `$('N').json.x`, or `$node[...]` is resolved directly with its native type preserved. An expression containing operators, arithmetic, or concatenation, such as `{{ $json.score % 2 }}`, is evaluated as JavaScript after each reference is substituted with its JSON value; a runtime error yields `null`.

<Note>
  `$items` is not available in workflow expressions. Only `$json`, `$input`, `$node[...]`, and `$(...)` are supported. `$items` exists only inside the [Code node's](/enterprise/api/superflow/node-types#code) JavaScript sandbox.
</Note>

## Complete minimal example

The following document defines a trigger feeding a Set node, with one `main` connection.

```json theme={null}
{
  "name": "Minimal Example",
  "nodes": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "name": "Trigger",
      "type": "lyzr-nodes-base.trigger",
      "typeVersion": 1,
      "parameters": {},
      "position": [240, 300]
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "name": "Set",
      "type": "lyzr-nodes-base.set",
      "typeVersion": 3.4,
      "parameters": {
        "assignments": {
          "assignments": [
            { "id": "f1", "name": "greeting", "type": "string", "value": "=Hello {{ $json.name }}" }
          ]
        }
      },
      "position": [480, 300]
    }
  ],
  "connections": {
    "Trigger": {
      "main": [
        [ { "node": "Set", "type": "main", "index": 0 } ]
      ]
    }
  },
  "settings": {}
}
```

Three details in this example are worth calling out. `connections` is keyed by node name ("Trigger"), not by `id`. `main[0]` is output slot 0, and its inner array holds the targets fed from that slot. The `=` prefix marks the Set value as an expression, so `{{ $json.name }}` resolves against the trigger's output item.

## Next steps

Every node type, with its parameters and outputs, is documented in the [node types reference](/enterprise/api/superflow/node-types). To submit a document like the one above, see [Create Workflow](/enterprise/api/superflow/workflows/create).