Skip to main content

Workflows

The state machines work moves through — states, the transitions between them, their guards, and the automation each one fires.

Overview​

A workflow is a declaration, not an execution: it names the states a piece of work can be in, the legal moves between them, and what should happen on entering a state. The work itself is a task, and the runtime — not your client — decides whether a move is legal.

Every write that changes the machine bumps version and archives the previous one, so a task already in flight keeps running the machine it started on. That is the point of versioning here: editing a workflow must never rewrite the history of work already done.

This module is a verbatim mirror of the runtime: every field, method, status code and error shape is the runtime's own, re-rooted under the project in the path.

See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → Workflows.

Data Model​

Workflow​

FieldTypeDescription
idstring
project_idstring
namestring
descriptionstring, nullable
versionintegerIncremented on every write that changes the state machine; prior versions are archived. A task pins the version it entered on, so these fields are a draft for tasks created from now on rather than a live rewrite of the ones already in flight.
statesobject[]
transitionsobject[]
payload_schemaobject, nullable
created_atstring (date-time)
updated_atstring (date-time)

states are what a task can occupy, transitions the legal moves, and payload_schema validates a task's payload.

WorkflowState​

FieldTypeDescription
namestring
initialboolean
terminalboolean
kindstringhuman marks a human-in-the-loop parking state: the state never dispatches (declaring on_enter on it is rejected at validation) and the task parks until a principal fires a transition.
stalled_afterinteger, nullableSeconds a task may sit in this state before the stall sweeper emits a tasks.stalled event (once per stall episode, re-armed on the next transition). Must be a positive integer when set. Omit or null to never stall. The event does not move the task — route on it with a webhook/trigger.
on_enterobject, nullableWhat entering the state dispatches, and how the result routes. Omitted or null on a state that only parks.

name is required and unique within the workflow. A task starts in the initial state; reaching a terminal one closes it. on_enter dispatches an agent, a tool or an orchestration.

WorkflowTransition​

FieldTypeDescription
namestring
fromstring[]
tostring
guardobject, nullable
requires_approvalbooleanGate the transition behind a human approval. When true, firing the transition (by anyone other than the approval resolution itself) parks a pending ApprovalItem instead of moving the task; the task exposes pending_transition until the item resolves. Approval fires the transition as the approval principal (its guard re-evaluated at resolution time); rejection or expiry clears the gate and appends a history note.

name, from and to are required: name is what you pass when moving a task, from the states the move is legal from, to the destination. guard is JSON Logic over the task; a falsy result refuses the move.

WorkflowVersion​

FieldTypeDescription
idstringPublic ID of the archived version
workflow_idstringPublic ID of the workflow this version belongs to
versionintegerThe archived version number
configobjectThe workflow's versioned surface as it stood at this version: states, transitions and payload_schema. Name and description are metadata — bumping the version when one of them changes would make two version numbers denote the same state machine, which is exactly what a task cites. Deliberately open rather than a fixed schema: an archive written by an earlier release of the runtime reflects the workflow surface of its own time, so it may carry fields the current API no longer documents.
labelstring, nullableOptional human tag for this version, e.g. rewired. Set from the version_label field of a write, the label field of a restore, or generated for one.
created_by_principal_typestring, nullableWho produced this version. Null for a write with no principal behind it.
created_by_principal_idstring, nullablePublic id of that principal: the user (user_…), or for API key auth the key itself (key_…), so the record names which key acted.
created_atstring (date-time)

For key auth, created_by_principal_id is the id of the project's key the request ran on, not the key the caller sent.

Key Concepts​

Versioning​

PATCH /v1/projects/{project_id}/workflows/{workflow_id} archives the machine as it was and bumps version. A task records its workflow_version at creation and keeps it, so rewiring a workflow never retroactively changes what an in-flight task was allowed to do. Read the archive with GET /v1/projects/{project_id}/workflows/{workflow_id}/versions and put an old machine back with POST /v1/projects/{project_id}/workflows/{workflow_id}/versions/{version}/restore, which is itself a new version rather than an edit of history.

Migrating every open task​

A task moves onto a newer version only when asked: POST /v1/projects/{project_id}/tasks/{task_id}/migrate moves one, POST /v1/projects/{project_id}/workflows/{workflow_id}/migrations moves every open task on an older version (or none) onto to_version, applying one state_map to all of them. A task the single route would refuse is reported refused with its error and the run goes on. The run settles in the background; read each task's outcome with GET /v1/projects/{project_id}/workflows/{workflow_id}/migrations/{migration_id}, or pass wait: true. Neither route fires the mapped state's on_enter, so a migration starts no generation. Each migrated task emits a tasks.migrated event.

Guards and approvals are the runtime's decision​

A guard is JSON Logic evaluated over the task; requires_approval parks the move for a person. Both are enforced upstream, which is why an illegal move comes back as a 409 from the runtime rather than something this API decides.

A guard is checked again when an approval resolves. If it no longer holds, the move is not applied: the task stays where it was, the approval still reads approved, and the only trace is a tasks.approval_failed webhook event.

Automation hangs off states, not transitions​

on_enter is what makes a workflow do work: entering a state dispatches an agent, a tool or an orchestration, and its result drives the next move. A human state deliberately dispatches nothing. Model a process as a workflow dispatches a writer agent on entering draft and waits for a person in a human review state.

Who may do what​

Every route needs any project member.

Examples​

Declare a two-state workflow​

naturali create-workflow \
--project-id proj_V1StGXR8Z5jdHi6B \
--name invoice-review \
--states '[{ "name": "open", "initial": true }, { "name": "approved", "terminal": true }]' \
--transitions '[{ "name": "approve", "from": ["open"], "to": "approved" }]'

Add a guarded, approval-gated move​

naturali update-workflow \
--project-id proj_V1StGXR8Z5jdHi6B \
--workflow-id wfl_V1StGXR8Z5jdHi6B \
--version-label pre-rewire \
--transitions '[{ "name": "approve", "from": ["open"], "to": "approved", "guard": { "<": [{ "var": "task.payload.amount" }, 10000] }, "requires_approval": true }]'

Read the version history​

naturali list-workflow-versions \
--project-id proj_V1StGXR8Z5jdHi6B \
--workflow-id wfl_V1StGXR8Z5jdHi6B