Notifications API

Manage notifications, push subscriptions, real-time SSE streaming, and notification preferences.

The Notifications API provides access to in-app notifications, push subscription management, real-time Server-Sent Events (SSE) streaming, and user notification preferences. All endpoints require authentication.

List Notifications

GET /api/v1/notifications — Required

Unread Count

GET /api/v1/notifications/unread-count — Required

Mark as Read

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

Real-Time Stream (SSE)

GET /api/v1/notifications/stream — Required

Push Subscribe

POST /api/v1/notifications/subscribe — Required

Preferences

GET / PUT /api/v1/notifications/preferences — Required

List Notifications

Retrieve paginated notifications for the authenticated user.

GET /api/v1/notifications — Auth: Required

Query parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number
`limit`	integer	`10`	Items per page

  curl "https://api.qriotag.global/api/v1/notifications?page=1&limit=20" \
    -H "Authorization: Bearer <token>"

Response

{
  "success": true,
  "data": [
    {
      "id": "ntf_001",
      "type": "TAG_SCANNED",
      "title": "Your tag was scanned",
      "body": "Someone scanned your House Keys tag in New York",
      "read": false,
      "data": { "tagId": "tag_abc123" },
      "createdAt": "2025-06-01T15:30:00.000Z"
    },
    {
      "id": "ntf_002",
      "type": "MESSAGE_RECEIVED",
      "title": "New message from finder",
      "body": "Alex sent you a message about House Keys",
      "read": true,
      "data": { "threadId": "thr_abc123" },
      "createdAt": "2025-06-01T15:35:00.000Z"
    }
  ],
  "meta": {
    "total": 15,
    "page": 1,
    "totalPages": 1
  }
}

Get Unread Count

Get the number of unread notifications.

GET /api/v1/notifications/unread-count — Auth: Required

  curl https://api.qriotag.global/api/v1/notifications/unread-count \
    -H "Authorization: Bearer <token>"

Response

{
  "success": true,
  "data": {
    "count": 3
  }
}

Mark Notification as Read

Mark a single notification as read.

PATCH /api/v1/notifications/:id/read — Auth: Required

  curl -X PATCH https://api.qriotag.global/api/v1/notifications/ntf_001/read \
    -H "Authorization: Bearer <token>"

Response

{
  "success": true,
  "data": {
    "message": "Notification marked as read"
  }
}

Mark All as Read

Mark all notifications as read.

POST /api/v1/notifications/read-all — Auth: Required

  curl -X POST https://api.qriotag.global/api/v1/notifications/read-all \
    -H "Authorization: Bearer <token>"

Response

{
  "success": true,
  "data": {
    "message": "All notifications marked as read",
    "count": 3
  }
}

POST /api/v1/notifications/subscribe — Auth: Required

Request body

Field	Type	Required	Description
`subscription`	object	Yes	Web Push subscription object from the browser
`subscription.endpoint`	string	Yes	Push service URL
`subscription.keys.p256dh`	string	Yes	Public key
`subscription.keys.auth`	string	Yes	Auth secret

  curl -X POST https://api.qriotag.global/api/v1/notifications/subscribe \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "subscription": {
        "endpoint": "https://fcm.googleapis.com/fcm/send/abc123...",
        "keys": {
          "p256dh": "BNcRdreALRFXTkOOUHK1EtK2wtaz5Ry4YfYCA_0QTpQtUbVlUls0VJXg7A8u-Ts1XHhAirjS9v7UHyBMW...",
          "auth": "tBHItJI5svbpC7sc3fM..."
        }
      }
    }'

Response

{
  "success": true,
  "data": {
    "message": "Push subscription registered"
  }
}

Unsubscribe from Push Notifications

Remove the push subscription for the current device.

POST /api/v1/notifications/unsubscribe — Auth: Required

  curl -X POST https://api.qriotag.global/api/v1/notifications/unsubscribe \
    -H "Authorization: Bearer <token>"

Response

{
  "success": true,
  "data": {
    "message": "Push subscription removed"
  }
}

Real-Time Notification Stream (SSE)

Open a Server-Sent Events connection to receive notifications in real time.

GET /api/v1/notifications/stream — Auth: Required

  curl -N https://api.qriotag.global/api/v1/notifications/stream \
    -H "Authorization: Bearer <token>" \
    -H "Accept: text/event-stream"

SSE connection

This is a long-lived connection. The server sends events as they occur. Use -N with curl to disable buffering. In JavaScript, use the EventSource API.

Event format

event: notification
data: {"id":"ntf_003","type":"TAG_SCANNED","title":"Your tag was scanned","body":"Someone scanned House Keys","createdAt":"2025-06-01T16:00:00.000Z"}

event: notification
data: {"id":"ntf_004","type":"MESSAGE_RECEIVED","title":"New message","body":"Alex replied to your conversation","createdAt":"2025-06-01T16:05:00.000Z"}

JavaScript example

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

eventSource.addEventListener('notification', (event) => {
  const notification = JSON.parse(event.data);
  console.log('New notification:', notification);
});

Get Notification Preferences

Retrieve the user's notification preference settings.

GET /api/v1/notifications/preferences — Auth: Required

  curl https://api.qriotag.global/api/v1/notifications/preferences \
    -H "Authorization: Bearer <token>"

Response

{
  "success": true,
  "data": {
    "email": {
      "tagScanned": true,
      "messageReceived": true,
      "statusChange": true,
      "marketing": false
    },
    "push": {
      "tagScanned": true,
      "messageReceived": true,
      "statusChange": true
    }
  }
}

Update Notification Preferences

Update notification preference settings.

PUT /api/v1/notifications/preferences — Auth: Required

Request body

Field	Type	Required	Description
`email`	object	No	Email notification settings
`email.tagScanned`	boolean	No	Notify on tag scans
`email.messageReceived`	boolean	No	Notify on new messages
`email.statusChange`	boolean	No	Notify on tag status changes
`email.marketing`	boolean	No	Receive marketing emails
`push`	object	No	Push notification settings
`push.tagScanned`	boolean	No	Push on tag scans
`push.messageReceived`	boolean	No	Push on new messages
`push.statusChange`	boolean	No	Push on tag status changes

  curl -X PUT https://api.qriotag.global/api/v1/notifications/preferences \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "email": {
        "tagScanned": false,
        "marketing": false
      },
      "push": {
        "tagScanned": true,
        "messageReceived": true
      }
    }'

Response

{
  "success": true,
  "data": {
    "message": "Notification preferences updated"
  }
}

Was this page helpful?

Notifications API

List Notifications

Unread Count

Mark as Read

Real-Time Stream (SSE)

Push Subscribe

Preferences

On this page