Tasks
Units of work moving through a workflow — each transition guarded, dispatched and recorded.
Overview
A task is one item of work: it names the workflow it runs on, the state it is
currently in, and a caller-owned payload. Moving it is not an update — you fire
a transition by name and the runtime decides whether that move is legal from
the current state, evaluating the workflow's guard and parking the move if it
requires approval.
Entering a state can dispatch automation (the workflow's on_enter), so a task
is also the thing that drives agents, tools and
orchestrations without a caller in the loop. Every move is
appended to an immutable history, including the ones a machine made.
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 → Tasks.
Data Model
Task
| Field | Type | Description |
|---|---|---|
id | string | |
project_id | string | |
workflow_id | string | |
workflow_version | integer, nullable | The workflow version this task runs on, fixed when the task was created. Transitions, approval gates and payload validation all resolve through it, so editing the workflow never re-shapes a task already in flight. null for tasks created before pinning existed, which run on the live definition. |
title | string | |
state | string | |
status | open | closed | |
payload | object | Caller-owned task data; input to guards (as task.payload) and dispatch mappings. The engine never writes into it except the workflow's declared payload_writes. |
metadata | object | The caller-owned key/value metadata supplied when the task was created, returned verbatim. Absent when the task was created without any. Unlike payload it is invisible to guards and to payload_writes, so it is the place for an attribution label rather than task data. |
last_result | any | Server-owned. The result of the current state's last completed dispatch, overwritten on every dispatch. Read-only — exposed to transition guards and on_complete/payload_writes expressions as task.last_result, a namespace a caller cannot write. An agent dispatch's result is the generation's output plus ai_provider_id, the provider that served its model (null when the route that ran named no serving target). |
assignee | string, nullable | |
priority | very_high | high | medium | low | very_low, nullable | A person's assertion of how much the task matters, never derived. null until someone sets it. Set and cleared only with set-task-priority; readable by guards as task.priority. |
active_dispatch | object, nullable | { kind, id, status } of the current state's dispatch, if any. kind is generation, orchestration_run or tool_call; a tool_call always carries a null id, since a direct tool call leaves no addressable record. Carries an additional attempt (1-based) while the state's on_enter.retry policy is in effect. |
automation_status | running | completed | failed | unrouted | paused, nullable | Status of the current state's dispatch. null until a state with an automation is entered. paused means an operator pause suppressed this state's on_enter before it ran, so resume-task will start it. |
pause_requested_at | string (date-time), nullable | When an operator paused this task's automation, or null when no pause is in force. |
pause_reason | string, nullable | The reason supplied with the pause, when one was. |
automation_chain_depth | integer | Server-owned. How many machine-driven transitions have run back-to-back with no outside intervention — a dispatch outcome routed through on_complete/on_failure, or a transition-task call made by a dispatched run or agent under its stored authority. Any move by a person, a plain API key, or an approval resolution resets it to 0. Once it would exceed the server's limit (TASK_AUTOMATION_CHAIN_LIMIT, default 50) the next such transition is refused with TASK_AUTOMATION_CHAIN_LIMIT, bounding a cycle composed across workflows and orchestrations. |
pending_transition | string, nullable | The name of a requires_approval transition parked awaiting a human decision. Non-null while an ApprovalItem gates the move; the task stays in its current state and no other transition may fire until the approval resolves. |
readiness | object | Computed on every read. Only an open dependency blocks; any close, cancelled included, frees what the task held. Guards read it as task.readiness. |
entered_state_at | string (date-time) | |
created_at | string (date-time) | |
updated_at | string (date-time) |
state is the current state's name; reaching a terminal state closes the task.
TaskTransition (history entry)
| Field | Type | Description |
|---|---|---|
id | string | |
task_id | string | |
from_state | string, nullable | |
to_state | string | |
transition | string, nullable | |
principal_type | string | Who made the move: user or api_key for an authenticated caller, automation for the engine acting on an on_enter dispatch outcome, approval for an approval resolution. Named principal_*, not actor_*: these ids never reference the Actors module. |
principal_id | string, nullable | Public id of the principal that made the move — the user (user_...), or for api_key auth the key's own id (key_...), distinguishing which key acted. Null for automation, which has no principal: the cause is carried by generation_id / orchestration_run_id / tool_id, one per dispatch kind — exactly one of which is set on an automation move. |
generation_id | string, nullable | Set when an agent dispatch's generation caused the move. |
orchestration_run_id | string, nullable | Set when an orchestration dispatch's run caused the move. |
tool_id | string, nullable | Set when a tool dispatch caused the move. A tool call produces no addressable record of its own, so the tool it called is what records why the task moved. |
note | string, nullable | |
from_workflow_version | integer, nullable | Set on a migration row only: the version the task left, or null for a task that had no pinned version. |
to_workflow_version | integer, nullable | Set on a migration row only, the version the task moved onto. |
created_at | string (date-time) |
transition is the transition's name.
Key Concepts
You fire a transition, not a state
POST /v1/projects/{project_id}/tasks/{task_id}/transitions
takes a transition name. An undeclared name is a 400; a name that is not
legal from the current state is a 409. Both come from the runtime, which is
what makes the workflow the single source of truth about legal moves —
PATCH /v1/projects/{project_id}/tasks/{task_id}
edits the title, assignee and payload, and never the state.
Model a process as a workflow
fires revise to send a task back to an earlier state.
A task is pinned to a workflow version
workflow_version is
stamped at creation
and never moves. Rewiring the
workflow leaves
in-flight tasks on the machine they started on.
Automation, and the loop bound
If the entered state declares on_enter, the task dispatches it and reports
progress through active_dispatch and automation_status. A dispatch may itself
transition the task,
which is recorded with principal_type: automation;
automation_chain_depth counts how many such moves have run back-to-back, which
is what stops a workflow from looping forever without a human or a client.
A dispatch runs under the authority the task stores: that of whoever last moved
it, or of the run an automated move carries on. A task that stores none runs no
tool: 409 WORK_AUTHORITY_MISSING.
A pause stops the automation, not the board
POST /v1/projects/{project_id}/tasks/{task_id}/pause
suppresses every dispatch a state would start — an agent generation, a tool call,
an orchestration — and abandons a retry chain's remaining attempts, so the task
stops spending without losing its place. Transitions keep working under it: a move
costs nothing while the dispatch it would start is suppressed, so a board stays
usable. A state entered under a pause records automation_status: paused, and
POST /v1/projects/{project_id}/tasks/{task_id}/resume
is the only thing that lifts one — it starts the dispatch the pause suppressed and
leaves a state whose work had already completed alone.
A negative balance stops what a task would dispatch
Entering a state can generate, so
POST /v1/projects/{project_id}/tasks,
POST /v1/projects/{project_id}/tasks/{task_id}/transitions
and
POST /v1/projects/{project_id}/tasks/{task_id}/resume
answer 402 INSUFFICIENT_CREDIT and dispatch nothing while the project owes for
usage already served. It is the project owner's balance. See
A negative balance stops managed generation.
A Free account that has used its plan's monthly runs answers
403 PLAN_LIMIT_REACHED with resource: "runs" here as well, on its own
credential too. See
A plan's run allowance can stop generation.
This holds however the call arrives: a call to this API or an agent's tool call.
Only a move that would dispatch is refused: a create whose entry state (state,
else the initial one) declares on_enter in the workflow's current version, a
transition into a state whose on_enter is declared in the task's pinned
workflow version (approval-gated or not), and a resume of a task whose
automation_status is paused. A move into
a state that only parks goes through. Reading, closing and pausing are never
refused — a pause is how the debt stops growing.
An automation chain already dispatching is paused instead. A chain runs on
nobody's request, so nothing can refuse it; the reconciliation that discovers the
debt pauses every open task whose automation_status is running, with a
pause_reason saying to top up. A task whose automation has come to rest is left
alone, since what would start it again is a transition into a dispatching state,
which is refused meanwhile.
Find a task by a field you keep in metadata
GET /v1/projects/{project_id}/tasks takes
?metadata=, a JSON object url-encoded into one parameter, so a task carrying
your own record id is found by it without keeping a map of task ids. The match
is exact ({"external_id": 42} and {"external_id": "42"} are different
filters); { "in": [...] } matches any listed value and gt, gte, lt,
lte order a field by the operand's type. It narrows alongside state,
status and assignee; malformed JSON or an operand with no order is
400 VALIDATION_FAILED. The same grammar filters
documents.
Priority is a person's to set
priority is very_high, high, medium, low, very_low, or null when
nobody prioritised the task. Only
PUT /v1/projects/{project_id}/tasks/{task_id}/priority
sets it, and null clears it; create and update do not accept it.
GET /v1/projects/{project_id}/tasks filters on
priority (repeat it to OR values; none selects the unprioritised), and
guards read it as task.priority.
?order=next lists in pull order: effective priority (the highest of the task
and every open task it blocks, transitively; null lowest), then
readiness.unblocks descending, then oldest in its state. It composes with
every filter and answers one page: limit applies, a cursor is 400.
A task can wait on others
POST /v1/projects/{project_id}/tasks/{task_id}/dependencies
{ depends_on_task_id, note? } makes the task wait on another in the project,
across workflows: it is blocked while that task is open. A cycle is
409 TASK_DEPENDENCY_CYCLE (meta.path), the task itself
400 TASK_DEPENDENCY_SELF, and a closed task cannot gain one
(409 TASK_DEPENDENCY_CLOSED).
GET …/dependencies and
GET …/dependents list both sides;
DELETE …/dependencies/{depends_on_task_id}
removes one.
Every read carries readiness (blocked, blocked_by, blocked_by_count,
unblocks). Any close, cancelled included, frees what the task held. Readiness
gates nothing on its own: a guard reads task.readiness.blocked to hold a
transition, and ?blocked=true (or false) filters a board by it.
The history is the audit trail
GET /v1/projects/{project_id}/tasks/{task_id}/history
returns every move in order, each naming who made it and what caused it — the
generation, the run or the tool. It is append-only.
Model a process as a workflow
reads one with a move back to an earlier state in it.
To follow a task without polling, subscribe a webhook
to tasks.*: every creation, move, migration, close, stall, pause and automation outcome
is delivered with the task as its GET reads it.
Who may do what
Every route needs any project member.
Examples
Open a task on a workflow
- CLI
- SDK
- curl
naturali create-task \
--project-id proj_V1StGXR8Z5jdHi6B \
--workflow-id wfl_V1StGXR8Z5jdHi6B \
--title "Invoice 4471" \
--payload '{ "amount": 4200, "customer": "acme" }'
const { data: task } = await naturali.tasks.createTask({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: {
workflow_id: 'wfl_V1StGXR8Z5jdHi6B',
title: 'Invoice 4471',
payload: { amount: 4200, customer: 'acme' },
},
});
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/tasks \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "wfl_V1StGXR8Z5jdHi6B",
"title": "Invoice 4471",
"payload": { "amount": 4200, "customer": "acme" }
}'
Find a task by your own record id
- CLI
- SDK
- curl
naturali list-tasks \
--project-id proj_V1StGXR8Z5jdHi6B \
--metadata '{"source":"zendesk","external_id":"8123"}'
const { data } = await naturali.tasks.listTasks({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
query: {
metadata: JSON.stringify({ source: 'zendesk', external_id: '8123' }),
},
});
curl -G https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/tasks \
-H "Authorization: Bearer $NATURALI_TOKEN" \
--data-urlencode 'metadata={"source":"zendesk","external_id":"8123"}'
Move it through a declared transition
- CLI
- SDK
- curl
naturali transition-task \
--project-id proj_V1StGXR8Z5jdHi6B \
--task-id task_V1StGXR8Z5jdHi6B \
--transition approve \
--note "under the 10k limit"
const { data: moved } = await naturali.tasks.transitionTask({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
task_id: 'task_V1StGXR8Z5jdHi6B',
},
body: { transition: 'approve', note: 'under the 10k limit' },
});
console.log(moved?.state, moved?.pending_transition);
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/tasks/task_V1StGXR8Z5jdHi6B/transitions \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "transition": "approve", "note": "under the 10k limit" }'
Read who moved it, and why
- CLI
- SDK
- curl
naturali get-task-history \
--project-id proj_V1StGXR8Z5jdHi6B \
--task-id task_V1StGXR8Z5jdHi6B
const { data: history } = await naturali.tasks.getTaskHistory({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
task_id: 'task_V1StGXR8Z5jdHi6B',
},
});
for (const move of history ?? []) {
console.log(move.transition, move.principal_type, move.generation_id);
}
curl https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/tasks/task_V1StGXR8Z5jdHi6B/history \
-H "Authorization: Bearer $NATURALI_TOKEN"
Make a task wait on another
- CLI
- SDK
- curl
naturali add-task-dependency \
--project-id proj_V1StGXR8Z5jdHi6B \
--task-id task_V1StGXR8Z5jdHi6B \
--depends-on-task-id task_3OmBu0xBaYp1Nq7C
await naturali.tasks.addTaskDependency({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
task_id: 'task_V1StGXR8Z5jdHi6B',
},
body: { depends_on_task_id: 'task_3OmBu0xBaYp1Nq7C' },
});
const { data: task } = await naturali.tasks.getTask({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
task_id: 'task_V1StGXR8Z5jdHi6B',
},
});
console.log(task?.readiness?.blocked); // true until the blocker closes
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/tasks/task_V1StGXR8Z5jdHi6B/dependencies \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "depends_on_task_id": "task_3OmBu0xBaYp1Nq7C" }'