FCM Notification Dispatcher - API Contract

GET /api/v1/notification-dispatches/api/v1/notification-dispatches

List all notification dispatch records

Auth Required org_adminglobal_admin

Response Example

{
  "data": [
    {
      "id": "disp_7f8a9b0c1d2e",
      "recipient_id": "coord_9f8e7d6c",
      "channel": "push",
      "status": "delivered",
      "payload_title": "Peer Mentor Pause Notification",
      "sent_at": "2026-03-19T14:30:05.000Z"
    },
    {
      "id": "disp_3e4f5a6b7c8d",
      "recipient_id": "pm_551e8400",
      "channel": "in_app",
      "status": "delivered",
      "payload_title": "Pause Confirmation",
      "sent_at": "2026-03-19T14:30:06.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2
  }
}

GET /api/v1/notification-dispatches/api/v1/notification-dispatches/:id

Get details of a specific dispatch attempt

Auth Required org_adminglobal_admin

Response Example

{
  "id": "disp_7f8a9b0c1d2e",
  "recipient_id": "coord_9f8e7d6c",
  "channel": "push",
  "device_tokens_targeted": [
    "fcm_token_abc123",
    "fcm_token_def456"
  ],
  "status": "delivered",
  "fcm_message_id": "projects/eircodex/messages/0:1679229005000000%31bd1bdcf9fd7ecd",
  "payload": {
    "title": "Peer Mentor Pause Notification",
    "body": "Kari Nordmann has activated a pause effective 20 March 2026.",
    "data": {
      "event": "pause_activated",
      "peer_mentor_id": "pm_551e8400"
    }
  },
  "sent_at": "2026-03-19T14:30:05.000Z",
  "delivered_at": "2026-03-19T14:30:06.000Z"
}

POST /api/v1/notification-dispatches/api/v1/notification-dispatches

Dispatch a push or in-app notification to a recipient (dispatchPush, dispatchInApp, dispatchMultiChannel)

Auth Required coordinatororg_admin

Request Example

{
  "recipient_id": "coord_9f8e7d6c",
  "channel": "multi",
  "payload": {
    "title": "Peer Mentor Pause Notification",
    "body": "Kari Nordmann has activated a pause effective 20 March 2026. Reason: Personal leave.",
    "data": {
      "event": "pause_activated",
      "peer_mentor_id": "pm_551e8400"
    }
  }
}

Response Example

{
  "id": "disp_7f8a9b0c1d2e",
  "recipient_id": "coord_9f8e7d6c",
  "channels_dispatched": [
    "push",
    "in_app"
  ],
  "status": "delivered",
  "sent_at": "2026-03-19T14:30:05.000Z"
}

PUT /api/v1/notification-dispatches/api/v1/notification-dispatches/:id

Retry a failed dispatch or update its status

Auth Required org_adminglobal_admin

Request Example

{
  "action": "retry",
  "notes": "FCM token refresh, retrying delivery"
}

Response Example

{
  "id": "disp_7f8a9b0c1d2e",
  "status": "delivered",
  "retry_count": 1,
  "retried_at": "2026-03-26T09:40:00.000Z"
}

DELETE /api/v1/notification-dispatches/api/v1/notification-dispatches/:id

Delete a dispatch record

Auth Required global_admin

Response Example

{
  "message": "Dispatch record deleted",
  "deleted_id": "disp_7f8a9b0c1d2e",
  "deleted_at": "2026-03-26T09:45:00.000Z"
}

GET /api/v1/notification-dispatches/api/v1/notification-dispatches/device-tokens/:userId

Get all registered FCM device tokens for a user (getDeviceTokens)

Auth Required org_adminglobal_admin

Response Example

{
  "user_id": "coord_9f8e7d6c",
  "device_tokens": [
    {
      "token": "fcm_token_abc123",
      "device": "iPhone 15 Pro",
      "registered_at": "2026-01-10T08:00:00.000Z"
    },
    {
      "token": "fcm_token_def456",
      "device": "iPad Air",
      "registered_at": "2026-02-14T10:30:00.000Z"
    }
  ]
}

Additional Metadata

{
  "contract_summary": {
    "total_contracts": 410,
    "total_endpoints": 2416,
    "api_styles_used": [
      "rest"
    ]
  },
  "generated_at": "2026-03-26T06:55:53.316Z"
}