Skip to Content
Sophon Docs
API Reference

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

FieldTypeNotes
idstring^[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)
namestringDisplay name
enabledbooleanDefault true. Cron, channel, e-mail and signed-webhook triggers fire only while enabled
triggerobjectSee Triggers. Optional; a workflow without one runs manually
nodesarrayThe steps. See Nodes
edgesarrayThe connections. See Edges
agentIdstringThe agent whose context Run skill steps use
settingsobjectNew in 2.2. See Settings
sampleInputobjectNew 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

FieldTypeNotes
idstringUnique 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
typestringOne of the node types; case-sensitive
position{ x, y }Canvas position only; the engine ignores it. Missing positions are laid out
configobjectType-specific settings. config.__label is the display label; it cannot be used in an expression
onErrorstringstop (default), continue, retry or goto
retryCountintegerAttempts under retry (at least 1); default 0
retryDelayMsintegerWait between attempts; default 1000
timeoutMsintegerPer-attempt timeout; -1 for none. Omitted: the type's default

Node types

Keys marked ⟨E⟩ accept {{ … }} expressions.

TypeConfigOutput
action.skillskill (required), parameters (object; each string value ⟨E⟩), agentIdThe tool's result
action.llm_promptprompt (required, ⟨E⟩), provider, modelThe reply text. Each attempt records model, tokens and cost
action.send_messagechannel (required: config id, type or name), body (required, ⟨E⟩), recipient ⟨E⟩, subject ⟨E⟩Message sent to <name> (<type>)
action.execute_codelanguage (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_callurl (required, ⟨E⟩), method (default GET), headers (object, values ⟨E⟩), body ⟨E⟩, maxResponseBytesThe response body
action.create_update_filepath (required, ⟨E⟩, relative), content (required, ⟨E⟩), mode (create, overwrite or append)File written: <path>
action.sub_workflowworkflowId (required)The child run's result, including its runId
logic.if_elsecondition (required, ⟨E⟩)true or false
logic.switchexpression (required, ⟨E⟩), cases (list of case values)The resolved value
logic.waitduration (required, e.g. 30s, 5m)—
logic.loopmode (forEach or while), source (required, ⟨E⟩), maxIterations (default 100, 1-1000), continueOnIterationErrorA JSON array of each iteration's result
logic.parallelnonefork
logic.mergenone; join: "all" optional{ "<id>": "<output>" } for the inputs that ran
logic.error_handlernone{ error, errorNodeId }
data.set_variablename (required), value (required, ⟨E⟩)Writes $vars.<name>
data.transformexpression (required, ⟨E⟩)The resolved text
data.filtersource (required, JSON array, ⟨E⟩), condition (required, ⟨E⟩; each item is $vars.__item)The filtered array
data.aggregatesource (required, ⟨E⟩), operation (count, sum, min, max, join)The aggregate
approval.human_approvaldescription ⟨E⟩approved, rejected, edited, timedout or queued
approval.info_requestquestion (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: source is a JSON array; each iteration sees $vars.__loopItem and $vars.__loopIndex. A list longer than maxIterations fails the loop before the first iteration.
  • while: source is a condition, checked before each iteration; the loop ends after maxIterations.
  • Steps after the loop read $node.<loop id>.output, never a step inside the body.
  • A failing body step under stop fails the loop with Iteration <n>: …, unless continueOnIterationError is true (the iteration's result is then null).
  • A save refuses a loop without a body connection, a loop inside another loop, and a body that is entered from outside or escapes it. The host caps every loop at SOPHON__Workflows__MaxLoopIterations (1000).

An unconditioned connection from a loop counts as done.

Default timeouts

TypeDefault
approval.human_approval30 minutes
approval.info_request5 minutes
logic.waitits duration plus 5 seconds
action.sub_workflow, logic.loopnone (their own steps time themselves)
everything else30 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.

ClassTypes
readOnlyEvery logic.* and data.* type; action.api_call with GET, HEAD or OPTIONS (or no method); action.skill whose tool is read-only
idempotentaction.llm_prompt
effectfulaction.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
interactiveapproval.human_approval, approval.info_request

Edges

{ "from": "check_status", "to": "notify", "condition": "true" }
Source typeCondition values
logic.if_elsetrue, false (both required), error
logic.switcha case value, or default
approval.human_approvalan outcome (approved, rejected, …), error
logic.loopbody, done
logic.parallelnone, or fork
any typenone (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 }
FieldNotes
strictReferencestrue 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
maxConcurrency1-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
maxNodeExecutions1-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" }
}
FieldNotes
typemanual, cron, webhook, channel_message or email_received
expressioncron: a 5-field Unix or Quartz cron expression
timezonecron: a time zone id such as UTC or Europe/Berlin
channelTypechannel_message: the channel type; blank matches every channel except e-mail
patternchannel_message: a regex on the message text; email_received: a regex on the subject or body. Ignores case
filterConfigString 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') }}
RootResolves 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