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
| Field | Type | Description |
|---|---|---|
id | string | |
project_id | string | |
name | string | |
description | string, nullable | |
version | integer | Incremented 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. |
states | object[] | |
transitions | object[] | |
payload_schema | object, nullable | |
created_at | string (date-time) | |
updated_at | string (date-time) |
states are what a task can occupy, transitions the legal moves, and
payload_schema validates a task's payload.
WorkflowState
| Field | Type | Description |
|---|---|---|
name | string | |
initial | boolean | |
terminal | boolean | |
kind | string | human 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_after | integer, nullable | Seconds 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_enter | object, nullable | What 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
| Field | Type | Description |
|---|---|---|
name | string | |
from | string[] | |
to | string | |
guard | object, nullable | |
requires_approval | boolean | Gate 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
| Field | Type | Description |
|---|---|---|
id | string | Public ID of the archived version |
workflow_id | string | Public ID of the workflow this version belongs to |
version | integer | The archived version number |
config | object | The 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. |
label | string, nullable | Optional 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_type | string, nullable | Who produced this version. Null for a write with no principal behind it. |
created_by_principal_id | string, nullable | Public id of that principal: the user (user_…), or for API key auth the key itself (key_…), so the record names which key acted. |
created_at | string (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
- CLI
- SDK
- curl
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" }]'
const { data: workflow } = await naturali.workflows.createWorkflow({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: {
name: 'invoice-review',
states: [
{ name: 'open', initial: true },
{ name: 'approved', terminal: true },
],
transitions: [{ name: 'approve', from: ['open'], to: 'approved' }],
},
});
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/workflows \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"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
- CLI
- SDK
- curl
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 }]'
await naturali.workflows.updateWorkflow({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
workflow_id: 'wfl_V1StGXR8Z5jdHi6B',
},
body: {
version_label: 'pre-rewire',
transitions: [
{
name: 'approve',
from: ['open'],
to: 'approved',
guard: { '<': [{ var: 'task.payload.amount' }, 10000] },
requires_approval: true,
},
],
},
});
curl -X PATCH https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/workflows/wfl_V1StGXR8Z5jdHi6B \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"version_label": "pre-rewire",
"transitions": [
{ "name": "approve", "from": ["open"], "to": "approved",
"guard": { "<": [{ "var": "task.payload.amount" }, 10000] },
"requires_approval": true }
]
}'
Read the version history
- CLI
- SDK
- curl
naturali list-workflow-versions \
--project-id proj_V1StGXR8Z5jdHi6B \
--workflow-id wfl_V1StGXR8Z5jdHi6B
const { data: versions } = await naturali.workflows.listWorkflowVersions({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
workflow_id: 'wfl_V1StGXR8Z5jdHi6B',
},
});
curl https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/workflows/wfl_V1StGXR8Z5jdHi6B/versions \
-H "Authorization: Bearer $NATURALI_TOKEN"