Inbox

Your personal queue of human review tasks generated by running workflows.

The Inbox collects tasks that require a human decision before a workflow can continue. When a workflow reaches a user_approval node or an agent node running in review execution mode, execution pauses and an inbox task is created for the designated reviewer. The workflow resumes only after the task is decided.

---

When is an inbox task created?

Trigger	Config	What creates the task
user_approval node	assigned_group on the node	Runtime creates a task when the node is reached
agent node with execution_mode: review	assigned_group in node config	Runtime creates a task after the LLM produces its output

In both cases, the task appears in the inbox of every user with the matching role in the workflow's space. The first person to decide wins — the task is then marked decided and is no longer actionable.

---

Task statuses

Status	Meaning
pending	Awaiting a decision — the workflow is paused
decided	A decision was made; the workflow has resumed
expired	The deadline passed without a decision; resolved automatically
superseded	A later version of the task replaced this one (e.g. after delegation)

---

What reviewers see

Each task shows:

Field	Description
Title	Brief description of what needs reviewing
Workflow name	Which workflow is paused
Node label	Which node inside the workflow caused the pause
AI output preview	What the AI generated (for review mode nodes) or the message text (for user_approval nodes)
Input context	The full workflow state at the moment of pause — original input, prior node outputs
Time remaining	Countdown to expiry (if a deadline was configured on the node)
Assigned group	Which space role this task was sent to

---

Decisions

Four decisions are available on each task:

Approve

The AI's output is accepted as-is. The workflow resumes from where it paused, using the original AI output as the node's result.

POST /api/v1/inbox/{task_id}/decide
{
  "decision": "approve",
  "notes": "Looks correct — proceed."
}

Modify

The reviewer edits the AI's output. The workflow resumes using the modified version instead of what the AI produced. Downstream nodes receive the human-corrected output.

POST /api/v1/inbox/{task_id}/decide
{
  "decision": "modify",
  "modified_output": "Risk level: HIGH. The indemnification clause in section 4.2 creates unlimited liability exposure.",
  "notes": "AI underestimated the risk — corrected to HIGH."
}

modified_output is required when decision is modify.

Reject

The workflow is terminated. The run is marked rejected. No further nodes execute. A rejection requires notes explaining the reason.

POST /api/v1/inbox/{task_id}/decide
{
  "decision": "reject",
  "notes": "The AI output contains factually incorrect information about the contract dates. Needs manual processing."
}

Delegate

Re-assigns the task to a specific colleague without making a decision. The task remains pending but is now only visible to the named user. Useful when someone else is better placed to review.

POST /api/v1/inbox/{task_id}/decide
{
  "decision": "delegate",
  "delegated_to": "user-id-of-colleague"
}

---

Visibility rules

A user sees an inbox task if any of these apply:

1. Their space role matches the task's assigned_group in the task's space.
2. The task was delegated directly to them (assigned_user_id).
3. They are a global admin.

space_admin and lifecycle_manager roles see all tasks in their space regardless of which group the task was assigned to.

---

Task expiry and timeouts

Inbox tasks can have a deadline. If the deadline passes without a decision, the system resolves the task automatically based on the node's timeout_action setting:

timeout_action	What happens at expiry
auto_proceed (default)	Task is marked expired; workflow resumes using the original AI output as-is
reject	Task is marked expired; workflow is terminated (status rejected)

Expired tasks appear in the inbox with an expired badge for audit purposes — they can no longer be decided.

---

Real-time notifications

The inbox badge in the sidebar updates in real time via SSE. Connect to:

GET /api/v1/inbox/stream
Accept: text/event-stream

Events:

Event	When emitted	Fields
connected	On SSE connect	pending_count
new_task	When a new task is created for this user	task_id, pending_count
decided	When a task visible to this user is decided	task_id, pending_count
ping	Every 30 seconds	—

If Redis is unavailable, the stream falls back to ping-only mode. The badge count will still update correctly on page navigation.

---

API reference

GET  /api/v1/inbox                        # list tasks (paginated)
  ?status_filter=pending|decided|expired  # filter by status
  ?space_id=<space_id>                    # restrict to one space
  ?page=1                                 # 50 tasks per page

GET  /api/v1/inbox/count                  # pending count only (lightweight badge query)
  ?space_id=<space_id>

GET  /api/v1/inbox/stream                 # SSE real-time badge updates

GET  /api/v1/inbox/{task_id}              # full task detail

POST /api/v1/inbox/{task_id}/decide       # submit decision

---

Differences: Inbox vs Review Queue

These are two separate systems that can both be called "review" but serve different purposes:

	Inbox	Review Queue
Created by	Workflow runtime (running nodes)	Developer staging a workflow for deployment
Blocks	A specific run from continuing	The workflow from being published to production
Resolved by	Approve / modify / reject / delegate	Approve (publishes) or reject (returns to draft)
Where to find	Dashboard > Inbox	Admin > Workflows or Dashboard > Review Queue
Scope	A single run execution	The workflow definition itself
Roles	Any role assigned to the node	lifecycle_manager, space_admin, admin

Both systems feed from the same notification infrastructure (Redis pub/sub + SSE), so badges update instantly across both.