​

Notifications & Activity API

ProBeya provides two complementary systems for tracking events: Notifications for personal, user-scoped alerts (task assignments, mentions, status changes) and Activity for organization-scoped audit trail entries (who did what, when).

​

Notifications

User-scoped notification system with cursor-based pagination for infinite scroll. Unlike most other routers, notifications use protectedProcedure (not orgProcedure) because a user’s notifications span across all their organizations.

​

Endpoints

​

GET /api/v1/notifications

Paginated list of the authenticated user’s notifications, newest first. Uses cursor-based pagination for reliable results when new notifications arrive between page loads.

tRPC: notifications.list Auth: Bearer token required or session cookie Org context: Not required (user-scoped)

Parameters:

Response:

{
  "notifications": [
    {
      "id": "clx9nf001",
      "type": "action_assigned",
      "title": "You were assigned an action",
      "body": "Investigate root cause of batch 2847 deviation",
      "entityType": "action",
      "entityId": "clx9ac002",
      "read": false,
      "createdAt": "2026-04-01T14:30:00.000Z"
    }
  ],
  "nextCursor": "clx9nf020"
}

When nextCursor is undefined, there are no more pages.

​

GET /api/v1/notifications/unread-count

Count of unread notifications for the bell icon badge. This query is polled every 30 seconds by the frontend and uses an indexed query for performance.

tRPC: notifications.unreadCount Auth: Bearer token required or session cookie Org context: Not required (user-scoped)

Response:

{
  "count": 7
}

​

PATCH /api/v1/notifications/:id/read

Mark a single notification as read. Only works for notifications belonging to the authenticated user.

tRPC: notifications.markAsRead Auth: Bearer token required or session cookie Org context: Not required (user-scoped)

Parameters:

​

POST /api/v1/notifications/mark-all-read

Bulk mark all unread notifications as read for the current user. Triggered by the “Mark all as read” button.

tRPC: notifications.markAllAsRead Auth: Bearer token required or session cookie Org context: Not required (user-scoped)

​

POST /api/v1/notifications/device-token

Register a native device token for push notifications (APNs for iOS, FCM for Android). Uses upsert behavior — if the user already has a token for the same platform and organization, the existing token is updated.

tRPC: notifications.registerDeviceToken Auth: Bearer token required or session cookie Org context: Required

Parameters:

​

Activity (Audit Trail)

Organization-scoped audit trail that records all mutations across the platform. Activities are logged by mutation handlers (not by this router) using the logActivity helper function. This router provides read access.

​

Endpoints

​

GET /api/v1/audit

List recent activity events across the entire organization. Used by the dashboard Recent Activity panel.

tRPC: activity.listByOrg Auth: Bearer token required (scope: read:items) or session cookie Org context: Required

Parameters:

Response:

{
  "data": [
    {
      "id": "clx9al001",
      "entityType": "action",
      "entityId": "clx9ac002",
      "action": "action.created",
      "metadata": { "title": "Investigate batch deviation" },
      "createdAt": "2026-04-01T14:30:00.000Z",
      "actor": {
        "id": "clx9us001",
        "name": "John Smith",
        "email": "[email protected]",
        "image": "https://cdn.probeya.com/avatars/john.jpg"
      }
    }
  ]
}

​

GET /api/v1/audit/entity

Fetch activity log for a specific entity. Used on detail panels to show the “Activity” tab.

tRPC: activity.listByEntity Auth: Bearer token required (scope: read:items) or session cookie Org context: Required

Parameters:

Response:

Each activity entry includes actor details (name, email, image) and metadata about the change.

​

Common Activity Actions

​

Error Codes