Workflow JSON
The JSON format for Sophon workflows — fields, step types, connections, settings, triggers, and expressions.
Overview
A workflow definition is one JSON document. The Gateway stores each workflow as <dataDir>/workflows/{id}.json (written with PascalCase property names) and keeps the 20 newest earlier versions under <dataDir>/workflows/versions/{id}/. The REST API, the CLI (sophon workflows create --file, sophon workflows validate), Import JSON in the builder and the shipped templates use the camelCase form on this page.
This page describes the format as of v2.2.0. For how runs behave, see the Workflows guide.
Example
The shipped Web Digest template:
{
"id": "web-digest",
"name": "Web Digest",
"enabled": false,
"trigger": { "type": "cron", "expression": "0 0 9 * * ?", "timezone": "UTC" },
"nodes": [
{
"id": "fetch_page",
"type": "action.api_call",
"position": { "x": 100, "y": 100 },
"config": { "__label": "Fetch page", "url": "https://example.com/", "method": "GET" }
},
{
"id": "summarize",
"type": "action.llm_prompt",
"position": { "x": 100, "y": 240 },
"timeoutMs": 120000,
"config": {
"__label": "Summarize",
"prompt": "Summarize this web page in at most five short bullet points.\n\n{{ $node.fetch_page.output }}"
}
},
{
"id": "send_digest",
"type": "action.send_message",
"position": { "x": 100, "y": 380 },
"config": { "__label": "Send digest", "channel": "webchat", "body": "Web digest:\n{{ $node.summarize.output }}" }
}
],
"edges": [
{ "from": "fetch_page", "to": "summarize" },
{ "from": "summarize", "to": "send_digest" }
]
}Top-level fields
| Field | Type | Notes |
|---|---|---|
id | string | ^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$, not a device name or a reserved route name (from-template, test-node, check-credentials, tool-availability, trigger-types, runs, templates, validate, sample-input) |
name | string | Display name |
enabled | boolean | Default true. Cron, channel, e-mail and signed-webhook triggers fire only while enabled |
trigger | object | See Triggers. Optional; a workflow without one runs manually |
nodes | array | The steps. See Nodes |
edges | array | The connections. See Edges |
agentId | string | The agent whose context Run skill steps use |
settings | object | New in 2.2. See Settings |
sampleInput | object | New in 2.2, read-only here. See Sample input |
Server-owned fields. version, createdBy, ownerId, updatedBy, updatedAt and tenantId are set by the Gateway. Since v2.2.0 a value sent on save is ignored: version is 1 on create and increases by one on every save, the caller becomes creator and owner on create, and ownership changes only through POST /api/workflows/{id}/owner. A sampleInput sent on save is ignored too.
Nodes
| Field | Type | Notes |
|---|---|---|
id | string | Unique within the workflow. New steps must match ^[A-Za-z0-9_][A-Za-z0-9_-]{0,63}$; the builder and the agent generate ^[a-z][a-z0-9_]{0,47}$. An id with . cannot be referenced |
type | string | One of the node types; case-sensitive |
position | { x, y } | Canvas position only; the engine ignores it. Missing positions are laid out |
config | object | Type-specific settings. config.__label is the display label; it cannot be used in an expression |
onError | string | stop (default), continue, retry or goto |
retryCount | integer | Attempts under retry (at least 1); default 0 |
retryDelayMs | integer | Wait between attempts; default 1000 |
timeoutMs | integer | Per-attempt timeout; -1 for none. Omitted: the type's default |
Node types
Keys marked ⟨E⟩ accept {{ … }} expressions.
| Type | Config | Output |
|---|---|---|
action.skill | skill (required), parameters (object; each string value ⟨E⟩), agentId | The tool's result |
action.llm_prompt | prompt (required, ⟨E⟩), provider, model | The reply text. Each attempt records model, tokens and cost |
action.send_message | channel (required: config id, type or name), body (required, ⟨E⟩), recipient ⟨E⟩, subject ⟨E⟩ | Message sent to <name> (<type>) |
action.execute_code | language (required: python or csharp), code (required, ⟨E⟩), timeout (seconds, default 30) | stdout. The script also gets SOPHON_NODE_DATA, SOPHON_INPUT_DATA and SOPHON_TRIGGER_DATA |
action.api_call | url (required, ⟨E⟩), method (default GET), headers (object, values ⟨E⟩), body ⟨E⟩, maxResponseBytes | The response body |
action.create_update_file | path (required, ⟨E⟩, relative), content (required, ⟨E⟩), mode (create, overwrite or append) | File written: <path> |
action.sub_workflow | workflowId (required) | The child run's result, including its runId |
logic.if_else | condition (required, ⟨E⟩) | true or false |
logic.switch | expression (required, ⟨E⟩), cases (list of case values) | The resolved value |
logic.wait | duration (required, e.g. 30s, 5m) | — |
logic.loop | mode (forEach or while), source (required, ⟨E⟩), maxIterations (default 100, 1-1000), continueOnIterationError | A JSON array of each iteration's result |
logic.parallel | none | fork |
logic.merge | none; join: "all" optional | { "<id>": "<output>" } for the inputs that ran |
logic.error_handler | none | { error, errorNodeId } |
data.set_variable | name (required), value (required, ⟨E⟩) | Writes $vars.<name> |
data.transform | expression (required, ⟨E⟩) | The resolved text |
data.filter | source (required, JSON array, ⟨E⟩), condition (required, ⟨E⟩; each item is $vars.__item) | The filtered array |
data.aggregate | source (required, ⟨E⟩), operation (count, sum, min, max, join) | The aggregate |
approval.human_approval | description ⟨E⟩ | approved, rejected, edited, timedout or queued |
approval.info_request | question (required, ⟨E⟩) | The answer, or (no response) |
Any step can set "join": "all" in its config to run only when every incoming connection was taken (by default it runs when at least one was).
Removed in v2.2.0
action.discussion is retired. A save that contains it is refused with node_type_removed, and a run that contains it fails before any step runs. Any type outside the list above is refused on save with node_type_unknown.
API call response limit
Since v2.2.0 an action.api_call step reads at most maxResponseBytes of the response body: default 1,048,576 (1 MB), at most 10,485,760 (10 MB); larger values count as 10 MB, and zero, negative or non-integer values mean the default. A larger body fails the step with Response body is larger than maxResponseBytes … and nothing is kept. The Dashboard keeps the value when you edit the step but has no field for it.
Loops
A logic.loop repeats the steps reachable from its body connections once per iteration, one iteration at a time, then takes its done connections:
forEach:sourceis a JSON array; each iteration sees$vars.__loopItemand$vars.__loopIndex. A list longer thanmaxIterationsfails the loop before the first iteration.while:sourceis a condition, checked before each iteration; the loop ends aftermaxIterations.- Steps after the loop read
$node.<loop id>.output, never a step inside the body. - A failing body step under
stopfails the loop withIteration <n>: …, unlesscontinueOnIterationErroris true (the iteration's result is thennull). - A save refuses a loop without a
bodyconnection, a loop inside another loop, and a body that is entered from outside or escapes it. The host caps every loop atSOPHON__Workflows__MaxLoopIterations(1000).
An unconditioned connection from a loop counts as done.
Default timeouts
| Type | Default |
|---|---|
approval.human_approval | 30 minutes |
approval.info_request | 5 minutes |
logic.wait | its duration plus 5 seconds |
action.sub_workflow, logic.loop | none (their own steps time themselves) |
| everything else | 30 seconds |
A whole run is capped at SOPHON__Workflows__MaxRunDuration (24 hours by default).
Effect classes
New in 2.2. Every step has an effect class, recorded on each step run as effect. Testing an effectful step, or a re-run that would repeat one, needs "confirmEffects": true.
| Class | Types |
|---|---|
readOnly | Every logic.* and data.* type; action.api_call with GET, HEAD or OPTIONS (or no method); action.skill whose tool is read-only |
idempotent | action.llm_prompt |
effectful | action.send_message, action.create_update_file, action.execute_code, action.sub_workflow; action.api_call with any other method; any other or unknown skill; unknown or retired types |
interactive | approval.human_approval, approval.info_request |
Edges
{ "from": "check_status", "to": "notify", "condition": "true" }| Source type | Condition values |
|---|---|
logic.if_else | true, false (both required), error |
logic.switch | a case value, or default |
approval.human_approval | an outcome (approved, rejected, …), error |
logic.loop | body, done |
logic.parallel | none, or fork |
| any type | none (always taken after success), or error (taken on failure under continue or goto) |
Saving lower-cases and trims If / Else and Approval conditions (True becomes true). Switch values compare trimmed; every other condition compares exactly.
Settings
New in 2.2. settings is optional, and a save that leaves out a field keeps the stored value.
"settings": { "strictReferences": true, "maxConcurrency": 2, "maxNodeExecutions": 500 }| Field | Notes |
|---|---|
strictReferences | true on workflows created since v2.2.0, absent on older ones. An action step with a $node or $vars reference that does not resolve fails before it runs |
maxConcurrency | 1-8. Opts the run into running independent steps at the same time, up to this many (capped by SOPHON__Workflows__MaxConcurrentNodesPerRun, 4 by default). A logic.parallel step opts in too. Once stored it cannot be cleared; 1 runs one step at a time |
maxNodeExecutions | 1-5000. Lowers the number of steps a run tree may run, sub-workflows included |
Triggers
"trigger": {
"type": "email_received",
"pattern": "invoice",
"filterConfig": { "channelConfigId": "email-1", "from": "@example\\.com$", "cooldownSeconds": "60" }
}| Field | Notes |
|---|---|
type | manual, cron, webhook, channel_message or email_received |
expression | cron: a 5-field Unix or Quartz cron expression |
timezone | cron: a time zone id such as UTC or Europe/Berlin |
channelType | channel_message: the channel type; blank matches every channel except e-mail |
pattern | channel_message: a regex on the message text; email_received: a regex on the subject or body. Ignores case |
filterConfig | String values: channelConfigId (one of the owner's channel configs), from and subject (email_received, regexes), cooldownSeconds (0-86,400) |
file_change, calendar_event and agent_request are known spellings but never fire. Since v2.2.0 a save that introduces one is refused with trigger_type_unavailable; a stored one saves with a warning. GET /api/workflows/trigger-types answers { fireable, known }.
Expressions
{{ $node.fetch_page.output }}
{{ $node.lookup_user.output.email }}
{{ $trigger.data.event }}
{{ $input.threshold }}
{{ $vars.counter + 1 }}
{{ default($vars.__error, 'no error') }}| Root | Resolves to |
|---|---|
$node.<id>.output[.path] | A step's output; extra segments walk a JSON object |
$trigger.data[.path] | The trigger payload |
$input[.path] | The run input |
$vars.<name>[.path] | A variable |
Operators: ||, &&, == != > < >= <=, + - * /, !. Functions: len, lower, upper, now, contains, default, json. There is no array indexing. In a workflow without strictReferences, a reference that does not resolve stays as literal {{ … }} text.
On save, the Gateway checks every $node reference: ref_node_unknown (an error in a new step, a warning in a stored one), and the warnings ref_node_self, ref_node_downstream, ref_node_no_output_segment, ref_node_not_upstream, ref_node_exclusive_branch and expression_unclosed. The Dashboard refuses Save on ref_node_self, ref_node_downstream and ref_node_no_output_segment.
Sample input
New in 2.2. One pinned sample per workflow, written only through PUT and DELETE /api/workflows/{id}/sample-input:
"sampleInput": {
"data": { "threshold": 10 },
"triggerData": { "event": "deployment", "status": "success" },
"pinnedFromRunId": null,
"pinnedAt": "2026-11-10T09:00:00Z",
"untrusted": false
}data fills $input and triggerData fills $trigger.data for runs started with "useSampleInput": true and for step tests. A sample is at most 64 KB. It is visible only to the owner and same-tenant Admins, is not kept in versions or run snapshots, and is cleared by an ownership transfer.
Validation errors
A refused save answers 400:
{
"error": "workflow_invalid",
"message": "… (+1 more)",
"errors": ["…"],
"issues": [
{ "code": "ref_node_unknown", "severity": "error", "message": "…", "nodeId": "notify", "field": "body", "reference": "{{ $node.fetch.output }}" }
]
}A successful save answers the stored definition with issues (its warnings, [] when none). POST /api/workflows/validate and sophon workflows validate return the same issues without saving.
Where to go next
- Workflows guide — building, running and debugging
- REST API — the workflow routes