API Reference
Notifications

Notifications API

⚠️

Internal API. These endpoints power the FlowAlert dashboard and mobile app and authenticate with a session token — there is no public way to obtain one, and API keys cannot call them. Documented for transparency; may change without notice. The supported integration surface is POST /v1/events.

All endpoints require a Bearer token and workspace membership.

List notifications

GET /v1/workspaces/:workspaceId/notifications?limit=100

Returns notifications for the entire workspace, newest first.

Response 200:

[
  {
    "id": "ntf_abc123",
    "status": "SENT",
    "failedReason": null,
    "priority": "NORMAL",
    "requiresAck": true,
    "createdAt": "2026-05-11T12:00:00.000Z",
    "sentAt": "2026-05-11T12:00:01.000Z",
    "acknowledgedAt": null,
    "event": {
      "id": "evt_xyz",
      "eventKey": "booking.created",
      "title": "New Booking — John Smith"
    },
    "user": {
      "id": "usr_abc",
      "name": "Sarah Johnson",
      "email": "sarah@example.com"
    }
  }
]

Notification statuses

StatusDescription
QUEUEDCreated, waiting to be sent
SENTDelivered to FCM/APNs
DELIVEREDConfirmed delivered to device
OPENEDUser opened the notification
ACKNOWLEDGEDUser tapped Acknowledge
FAILEDDelivery failed — see failedReason

Common failure reasons

failedReasonCause
No registered devices for userUser has not installed the app or never signed in
FCM: all N device(s) failedPush token(s) are stale — device reinstalled or token expired

Acknowledge a notification

PATCH /v1/workspaces/:workspaceId/notifications/:notificationId
{ "status": "ACKNOWLEDGED" }

This is called automatically by the mobile app when a user taps Acknowledge.

GroupsAPI Keys