Assignments and Routing
Route open Actions to the right reviewer, use the shared queue, and avoid stale or duplicate decisions.
ActionBox keeps a shared inbox without turning routing into an implicit decision. An open Action can be unassigned, explicitly assigned by a manager, or claimed atomically by an eligible reviewer.
The three inbox views
The user Action list supports scope (also accepted as routing) with three values:
| View | Meaning | Useful for |
|---|---|---|
mine | Actions assigned to the current user | Personal review queue |
unassigned | Open Actions with no assignee | Shared triage queue |
all | All Actions in the active workspace | Managers and audit views |
The dashboard's Inbox uses Mine, Unassigned, and All. It also filters by status, live/test environment, Source, priority, and search text.
curl 'https://api.actionbox.cloud/v1/me/actions?status=open&scope=unassigned&environment=live' \
-H "Authorization: Bearer $ACTIONBOX_USER_TOKEN"Open Actions are ordered by priority (urgent, high, normal, low) and then by creation time. History uses terminal status and update time instead.
Assign an Action
Owners and admins can explicitly assign or unassign an open Action:
curl -X PATCH https://api.actionbox.cloud/v1/actions/act_…/assignment \
-H "Authorization: Bearer $ACTIONBOX_USER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"assignee_user_id":"usr_reviewer_…"}'Set assignee_user_id to null to return an Action to the shared queue:
{"assignee_user_id": null}Only open Actions can be assigned. The target must be an active member of the Action's workspace. Assignment and unassignment are recorded as Action events; assignment also schedules the appropriate notification for the recipient.
Claim from the shared queue
An owner, admin, or approver can claim an unassigned Action:
curl -X POST https://api.actionbox.cloud/v1/actions/act_…/claim \
-H "Authorization: Bearer $ACTIONBOX_USER_TOKEN"Claiming is atomic. If another reviewer wins the race, the losing request receives a conflict instead of silently replacing the assignee. A repeated claim by the same reviewer returns the current assignment.
Claim first, decide second
Claiming reserves responsibility; it does not resolve the Action. Read the current Action after claiming, then submit a decision with the version and fingerprint you reviewed.
Route at creation time
A Source can include assignee_user_id in POST /v1/actions when the target is already an active member of the Source's workspace:
{
"title": "Review the production migration",
"assignee_user_id": "usr_reviewer_…",
"options": [
{"id": "approve", "label": "Approve", "style": "primary"},
{"id": "hold", "label": "Hold", "style": "default"}
]
}If no assignee is supplied, the Action enters the shared queue and creation notifications can be published to active workspace approvers. A Source key cannot route an Action into another workspace.
What changes notifications
- Assign: the recipient receives an assignment notification.
- Reassign: the new recipient receives a reassignment notification; obsolete queued work is cancelled.
- Claim: the claimant receives a claimed notification.
- Unassign: the Action returns to the shared queue and queued assignment/reminder/escalation work is cancelled.
- Resolve, cancel, or expire: future notifications for the open Action are no longer eligible.
Read Notifications for timing and personal push preferences.
A safe review sequence
1. Open the current Action
Read its action_version and fingerprint after routing settles. Do not reuse a version copied from an earlier list response.
2. Claim or confirm assignment
Claim an unassigned Action, or let an owner/admin assign it. If the Action is already assigned to another person, review it with that person or route it deliberately.
3. Submit a bound decision
Post the typed response or option_id to /v1/actions/{action_id}/decision with the displayed binding. A material update returns ACTION_CHANGED and the decision must be reviewed again.
Routing is not authorization to execute
An assignment identifies the reviewer. A resolved Action records authorization, while the machine must still execute the operation and report its execution outcome separately.
Next: Decisions and outcomes, Workspaces and teams, or Creating Actions.