Authenticated API

This endpoint requires a valid JWT Bearer token. Accessible via the API gateway.

Notifications API

Manage push notifications, in-app notifications, and subscribe to real-time notification streams.

Overview

Attribute	Value
Base Path	/api/v1/notifications
Authentication	Bearer Token
Required Roles	restaurant_staff, restaurant_manager, customer_support, marketing, tenant_admin, platform_admin, system_admin, super_admin

Endpoints

Create Notification

Send a notification to a user.

POST /api/v1/notifications

Request Body

{
  "user_id": "user_abc123",
  "type": "order_ready",
  "title": "Order Ready",
  "body": "Your order #A-0042 is ready for pickup!",
  "data": {
    "order_id": "ord_xyz789",
    "action": "view_order"
  },
  "channels": ["push", "in_app"],
  "priority": "high"
}

Response 201 Created

{
  "id": "notif_001",
  "user_id": "user_abc123",
  "type": "order_ready",
  "title": "Order Ready",
  "body": "Your order #A-0042 is ready for pickup!",
  "status": "sent",
  "channels_sent": ["push", "in_app"],
  "created_at": "2026-01-24T18:30:00Z"
}

Notification Types

Type	Description	Default Channels
order_ready	Order ready for pickup	push, in_app
order_update	Order status changed	push, in_app
reservation_reminder	Upcoming reservation	push, sms
reservation_confirmed	Reservation confirmed	email, in_app
loyalty_reward	New reward available	push, in_app
promo	Promotional notification	push
system	System notification	in_app
chat	New chat message	push, in_app

Priority Levels

Priority	Behavior
low	Batched, may be delayed
normal	Standard delivery
high	Immediate delivery, prominent display
urgent	Immediate, bypass DND

---

Bulk Send Notifications

Send notifications to multiple users.

POST /api/v1/notifications/bulk

Request Body

{
  "user_ids": ["user_001", "user_002", "user_003"],
  "type": "promo",
  "title": "Flash Sale!",
  "body": "20% off all orders today only",
  "data": {
    "promo_code": "FLASH20"
  },
  "channels": ["push"],
  "scheduled_at": "2026-01-25T12:00:00Z"
}

Response

{
  "batch_id": "batch_abc123",
  "total_recipients": 3,
  "status": "scheduled",
  "scheduled_at": "2026-01-25T12:00:00Z"
}

---

List Notifications

Retrieve notifications for the authenticated user.

GET /api/v1/notifications

Query Parameters

Parameter	Type	Description
type	string	Filter by notification type
read	boolean	Filter by read status
limit	integer	Results per page (max 100)
before	string	Cursor for pagination

Response

{
  "data": [
    {
      "id": "notif_001",
      "type": "order_ready",
      "title": "Order Ready",
      "body": "Your order #A-0042 is ready for pickup!",
      "data": {"order_id": "ord_xyz789"},
      "read": false,
      "created_at": "2026-01-24T18:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "notif_000"
}

---

Get Notification

Retrieve a single notification.

GET /api/v1/notifications/{id}

---

Mark as Read

Mark a notification as read.

PUT /api/v1/notifications/{id}/read

Response 204 No Content

---

Delete Notification

Delete a notification.

DELETE /api/v1/notifications/{id}

Response 204 No Content

---

Real-Time Streaming

Stream Notifications (SSE)

Subscribe to real-time notification stream using Server-Sent Events.

GET /api/v1/notifications/stream

Query Parameters

Parameter	Type	Description
resume_token	string	Resume from previous position
replay_limit	integer	Max events to replay (default: 25, max: 100)

Response (text/event-stream)

: heartbeat

event: notification
id: notif_001
data: {"id":"notif_001","type":"order_ready","title":"Order Ready","body":"Your order is ready!"}

event: notification
id: notif_002
data: {"id":"notif_002","type":"chat","title":"New Message","body":"You have a new message"}

: heartbeat

Event Types

Event	Description
notification	New notification
read	Notification marked as read
deleted	Notification deleted
heartbeat	Keep-alive (every 15s)

Connection Example

const eventSource = new EventSource(
  '/api/v1/notifications/stream',
  { headers: { 'Authorization': 'Bearer <token>' } }
);

eventSource.addEventListener('notification', (event) => {
  const notification = JSON.parse(event.data);
  showNotification(notification);
});

eventSource.onerror = (error) => {
  // Handle reconnection
  console.log('Connection lost, reconnecting...');
};

Resume Token

Use the Last-Event-ID header or resume_token query parameter to resume from a specific position after reconnection.

GET /api/v1/notifications/stream?resume_token=notif_001

---

Device Registration

Register FCM Device

Register a device for push notifications.

POST /api/v1/notifications/devices

Request Body

{
  "token": "fcm_device_token_here",
  "platform": "android",
  "app_version": "3.0.0",
  "device_model": "Pixel 7"
}

Unregister Device

Remove a device from push notifications.

DELETE /api/v1/notifications/devices/{token}

---

Preferences

Get Notification Preferences

GET /api/v1/notifications/preferences

Response

{
  "push_enabled": true,
  "email_enabled": true,
  "sms_enabled": false,
  "quiet_hours": {
    "enabled": true,
    "start": "22:00",
    "end": "08:00",
    "timezone": "America/New_York"
  },
  "categories": {
    "order_updates": {"push": true, "email": true},
    "promotions": {"push": false, "email": true},
    "loyalty": {"push": true, "email": false},
    "chat": {"push": true, "email": false}
  }
}

Update Preferences

PUT /api/v1/notifications/preferences

---

Error Responses

Status	Code	Description
400	invalid_type	Notification type not recognized
400	invalid_channel	Channel not supported
404	notification_not_found	Notification ID not found
503	stream_unavailable	SSE stream not initialized

---

Related Documentation

• Notification Hub Guide - Setup guide
• WebSocket Events - Real-time events
• Pub/Sub Events - Event messaging