Assignments and Routing

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:

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.

If an assignee leaves, is removed, or is changed to the viewer role, ActionBox returns their open Actions to the unassigned queue. The change is recorded in the Action timeline and wakes connected clients so stale assignment state is not left behind.

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.

Route at creation time

For POST /v1/actions, choose one assignment field:

Assign by email

{
  "title": "Review the production migration",
  "assignee_email": "reviewer@example.com"
}

Email matching is case-insensitive and limited to the Source workspace.

Assign by user ID

{
  "title": "Review the production migration",
  "assignee_user_id": "usr_reviewer_…"
}

Find a user ID

1. Open Settings → Team.
2. Find the reviewer.
3. Select Copy user ID.

The ID is stable and globally unique, but it is not a credential. The reviewer must still be an active owner, admin, or approver in the Source workspace.

Client support

actionbox ask "Deploy to production?" --assignee-email reviewer@example.com

Or copy the member's stable ID from Settings → Team:

actionbox ask "Deploy to production?" --assignee-user-id usr_reviewer_…

Both assignment flags are optional. Use at most one.

Restrict an Action to named reviewers

Team integrations can keep a sensitive Action out of the general workspace queue:

{
  "title": "Approve emergency production access",
  "visibility": "restricted",
  "reviewer_emails": [
    "incident-commander@example.com",
    "security-lead@example.com"
  ]
}

Use one non-empty list: reviewer_emails or reviewer_user_ids. Each accepts up to 15 active owners, admins, or approvers from the Source workspace. Email matching is case-insensitive. The existing assignee_email or assignee_user_id field can also create a restricted Action with one reviewer.

Restricted Actions are visible to their reviewers and active workspace owners/admins. Only a named reviewer can decide or claim one. An optional assignee identifies the reviewer currently taking ownership and must already be in the reviewer list.

To require several reviewers to approve the same restricted Action, add an Approval Policy. Visibility controls who can see the Action; the policy controls whose votes can resolve it.

actionbox ask "Approve emergency access?" \
  --private \
  --reviewer-email incident-commander@example.com \
  --reviewer-email security-lead@example.com \
  --option approve=Approve \
  --option reject=Reject

MCP ask_human uses private: true with reviewer_emails or reviewer_user_ids. The Python and TypeScript SDKs use the REST field names.

Owners and admins can replace the list while the Action is open:

PATCH /v1/actions/{action_id}/reviewers
Content-Type: application/json

{"reviewer_user_ids":["usr_primary_…","usr_backup_…"]}

Removing a reviewer removes their server-side access immediately. It also clears the assignee if that person was removed and changes the Action version and fingerprint, so an older decision fails closed.

If you omit assignment

See Python SDK, TypeScript SDK, or Developer CLI for full creation examples.

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.

By default, a directly assigned Action notifies only its reviewer. Owners and admins can opt into manager copies in Settings → Notifications when they need visibility into every new assigned Action.

Read Notifications for timing and personal push preferences.

A safe review sequence

Next: Decisions and outcomes, Workspaces and teams, or Creating Actions.