---
title: "Task Inbox"
source: "https://docs.vertesiahq.com/processes/task-inbox"
markdown: "https://docs.vertesiahq.com/llms/processes/task-inbox.md"
---

# Task Inbox

Whenever a process hits a `human_task` node, the engine creates a task and waits for an answer. Agents can also create tasks through `ask_user`, which lets a user answer later from the same inbox. Users see those tasks in the **Task Inbox** (`/store/tasks`), a split-pane view with a filterable list on the left and the selected task's detail + response form on the right.

## What shows up in my inbox

The inbox filters to tasks that are actually mine to act on. Concretely, a task appears in the UI if:

- **it's unassigned** (available to anyone who can see the inbox), or
- **`task.assignee` is my user id**, or
- **`task.assignee` starts with `group:`** and I'm a member of that group.

Tasks assigned to other users or other groups are hidden. The filter runs client-side against the returned task page because the backend `list` endpoint only supports exact-assignee matching. Users with `task:read` or `task:manage` can read broader task lists; users without those permissions only get tasks the API allows them to read.

## Assignees

Every `human_task` node's `task.assignee` is one of:

- `group:` — owned by a group (most common for shared queues like `group:legal`).
- `<user_id>` — owned by one specific user.
- unset — up for grabs.

`role:` is **not** supported. Use `group:` for role-like semantics.

## Taking a task

When a task is addressed to a group you're in — or unassigned — the detail pane shows a **Take Task** button. Clicking it sets `assignee` to your user id, pinning the task to you so others know it's being worked. After claiming, the button falls away and the task shows your name as the assignee.

Note: in the current implementation, claiming a task calls the generic `PUT /api/v1/tasks/:taskId` endpoint which still requires `task:manage` permission. A dedicated self-claim endpoint that allows any eligible viewer to claim is planned; until then, claiming falls through the admin permission check.

## Filters

Along the top of the list:

- **Open** (default) — pending + in progress, the ones that need attention.
- **Pending** — not yet started.
- **In progress** — someone's working on it.
- **Completed** — already answered.
- **Cancelled** — tasks that were cancelled before completion.
- **All** — everything returned by the API for the current user.

## Submitting an answer

The detail pane renders `task.fields` as a form. Each field's type maps to an input:

- `select` → a dropdown with `options`.
- `text` → a textarea.
- `boolean` → a checkbox.
- `number`, `string` → the corresponding input.

Submitting a process task sends the answer back to the process workflow as a signal. The process resumes, applies writes per `node.writes`, and evaluates guards on the declared transitions (e.g. route to `store_output` when `legal_decision === "approve"`).

Submitting an agent `ask_user` task signals the agent conversation with the answer and resolves the pending ask so the agent can continue.

The important operational rule is that process-sourced tasks must resume the workflow, not only mark the task document as completed. Use the Task Inbox or the process run's **answer task** API path so the workflow receives the signal and the state chart advances.

## Opening the parent run

**Open Run** in the detail pane jumps to the full process-run observability view so you can see the state chart, read the context, and inspect earlier agent conversations before answering. This is often worth doing for anything more nuanced than a single approve/reject.