Notifications

Notifications help people notice work; they do not become the work. The Action and its event history remain authoritative even when a push is delayed, duplicated, or disabled.

What can appear in the notification center

The in-app record is user-scoped and tied to the active workspace. The notification list returns up to 100 published records, newest first.

Read and clear notifications

The dashboard Notifications page opens the linked Action and marks an unread record as read. You can also use the user-scoped API:

# List published notifications
curl 'https://api.actionbox.cloud/v1/notifications?unread_only=false' \
  -H "Authorization: Bearer $ACTIONBOX_USER_TOKEN"

# Read the navigation badge
curl https://api.actionbox.cloud/v1/notifications/summary \
  -H "Authorization: Bearer $ACTIONBOX_USER_TOKEN"

# Mark one read
curl -X POST https://api.actionbox.cloud/v1/notifications/ntf_…/read \
  -H "Authorization: Bearer $ACTIONBOX_USER_TOKEN"

# Mark every unread notification in the active workspace read
curl -X POST https://api.actionbox.cloud/v1/notifications/read-all \
  -H "Authorization: Bearer $ACTIONBOX_USER_TOKEN"

The summary returns unread_count; read-all also reports how many records were updated. Filtering or reading notifications never changes the linked Action.

Personal push preferences

In Settings → Notification preferences in the iPhone app, each user can control optional push delivery:

The preferences API accepts the same controls:

curl -X PATCH https://api.actionbox.cloud/v1/notification-preferences \
  -H "Authorization: Bearer $ACTIONBOX_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "push_enabled": true,
    "new_action_enabled": true,
    "assignment_enabled": true,
    "reminder_enabled": true,
    "escalation_enabled": false,
    "priorities": ["high", "urgent"],
    "quiet_hours_enabled": true,
    "quiet_start_minute": 1320,
    "quiet_end_minute": 480,
    "timezone": "America/Toronto"
  }'

Quiet-hour values are minutes after midnight (1320 is 22:00 and 480 is 08:00 in the selected timezone). In-app notifications remain retained even when push is disabled.

Workspace reminders and escalations

Owners and admins control the workspace-wide policy at Settings → Notifications or through:

GET   /v1/workspaces/notification-policy
PATCH /v1/workspaces/notification-policy

The policy contains:

• default_assignee_user_id, which routes new Actions without an explicit assignee to an active workspace reviewer;
• notify_managers_on_assigned_actions, which sends owners and admins a copy of the new-Action notification when another reviewer is assigned;
• reminders_enabled and reminder_minutes_before_expiry for assigned open Actions (an Action created inside that window receives its initial alert but not an immediate duplicate reminder);
• escalations_enabled and escalation_minutes_after_creation for unanswered Actions; and
• escalation_priorities, which selects the priority levels that escalate.

Both minute values accept values from 1 to 10,080. By default, only the assigned reviewer receives the immediate assignment notification. Manager copies are opt-in. Escalations target active owners and admins and exclude the current assignee. Updating the policy reschedules future notifications for open Actions. Removing a default reviewer or changing that person to viewer clears the default automatically.

The PATCH endpoint accepts partial updates, so an integration can change the default reviewer without resending unrelated timing settings.

Delivery behavior

• In-app notifications are durable records and are retained independently of push delivery.
• Push is optional and content-light: clients use opaque Action and workspace identifiers or a change hint to refresh authoritative state.
• Operating-system policy, device connectivity, and provider networks can delay or suppress push delivery.
• Test Actions are isolated from live delivery and do not publish normal push hints or callback side effects in the hosted service.
• Resolving, cancelling, expiring, unassigning, or reassigning an Action cancels obsolete scheduled notification work.

Next: Set up the iPhone app, Assignments and routing, or Webhooks and callbacks.