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

# Workflow JSON

Understand the B3OS workflow definition format used by the API, editor, templates, and Caddie-assisted workflows.

A workflow definition is a directed graph. The graph always has a `root` node, and every child reference must point to another node in the same `nodes` map.

**Use the editor for discovery**

The visual editor is the fastest way to learn the shape of trigger and action payloads. Export or inspect the
  resulting definition when you need to automate the same pattern through the API.

**Workflow graph model**

**root trigger**
  **action node**
  **branch or loop**
  **downstream node**
  **connector reference**
  **children**
  **control flow**
  **then / else / item**
  **server-side credential**

## Required Shape

```json
{
  "nodes": {
    "root": {
      "type": "manual",
      "payload": {},
      "children": ["next_node"]
    },
    "next_node": {
      "type": "log",
      "payload": {
        "message": "Hello"
      },
      "children": []
    }
  }
}
```

## Node Fields

| Field | Required | Description |
| --- | --- | --- |
| ` type ` | Yes | Trigger ID for root, action ID for all other nodes. |
| ` payload ` | Yes | JSON object validated against the trigger or action schema. |
| ` children ` | No | Ordered list of downstream node IDs. |
| ` connector ` | Conditional | Connector reference for actions that need external account, wallet, or bot access. |
| ` loopBody ` | Conditional | Child nodes executed per item for loop actions. |
| ` branch ` | Conditional | Branch label used under branch-capable parents. |

## Expressions

Expressions pull data from the trigger, previous nodes, workflow props, and loop state.

| Expression | Meaning |
| --- | --- |
| ` {{$trigger.body.amount}} ` | Field from manual, webhook, or event trigger input. |
| ` {{$nodes.fetch_price.result.price}} ` | Result from a previous node. |
| ` {{$props.asset}} ` | Reusable prop supplied by a template or workflow consumer. |
| ` {{$item}} ` | Current loop item. |
| ` {{$index}} ` | Current loop index. |

**Recommended**

Use readable IDs such as `fetch_price`, `check_threshold`, and `send_alert`. Stable IDs make expressions easier to
  review.

**Avoid**

If a value comes from a branch or loop, design a fallback path or only reference it inside the same branch context.

## Connector Reference

Use connector references for actions that need account access. The connector record stores credentials separately from the workflow definition.

```json
{
  "type": "send-telegram-message",
  "connector": {
    "type": "telegram-bot",
    "id": "conn_telegram_bot"
  },
  "payload": {
    "chatId": "123456789",
    "text": "Workflow result: {{$nodes.format_message.result.formatted}}"
  },
  "children": []
}
```

**Do not place secrets in payloads**

Store external credentials in connectors or service-side configuration. Payloads should contain business inputs, not
  raw tokens, wallet signing material, or provider secrets.

## Minimal Branch

```json
{
  "nodes": {
    "root": { "type": "manual", "payload": {}, "children": ["check_amount"] },
    "check_amount": {
      "type": "if",
      "payload": {
        "condition": {
          "$and": [{ "{{$trigger.body.amount}}": { "$gte": 100 } }]
        }
      },
      "children": ["send_large_alert", "send_small_alert"]
    },
    "send_large_alert": {
      "type": "log",
      "branch": "then",
      "payload": { "message": "Large amount" },
      "children": []
    },
    "send_small_alert": {
      "type": "log",
      "branch": "else",
      "payload": { "message": "Small amount" },
      "children": []
    }
  }
}
```

## Related Reference

**[Action reference](/actions/reference)**

Browse payload and result schemas for every action.
  **[Trigger reference](/actions/trigger-reference)**

Browse trigger configuration and result schemas.
  **[Expressions](/platform/expressions)**

Learn expression scope, evaluation, loops, and troubleshooting.