Backend APIs for notifications, including list, read/unread, notification types, preferences, and FCM topic subscription.

API Reference

This document lists the primary backend APIs used by clients (frontend, workers, mobile apps) to interact with the Notification System.

Note: These endpoints are implemented under communication/notifications/urls.py in crelio-app and are exposed under the /api-v3/notifications/ prefix in the application.

Curl examples (copy-ready)

The docs UI provides a copy button for code blocks. All curl snippets below are safe to copy and then adjust:

Replace $BASE_URL with your environment base URL.
Provide auth using your existing session method (cookie header / browser session / internal tooling).

1. Fetch Notifications (Inbox list)

`GET /api-v3/notifications/all`

Fetch a paginated list of notifications for the current user.

Query parameters

from – start date (ISO string)
to – end date (ISO string)
page – page number (default: 1)
limit – page size (defaults to 1000; max 10000)

Curl

BASE_URL="https://<env-host>"

curl -sS "${BASE_URL}/api-v3/notifications/all?from=2026-03-01&to=2026-03-16&page=1&limit=50" \
  -H "Accept: application/json" \
  -H "Cookie: sessionid=<your-session-cookie>"

Response (simplified)

{
  "message": "success",
  "data": [
    {
      "id": 1,
      "message": {
        "title": "Critical report ready",
        "body": "Report #12345 is ready for review",
        "data": {}
      },
      "created_at": 1708000000,
      "read_on": null,
      "notification_activities": [],
      "read_by_username": null
    }
  ]
}

2. Mark Notification as Read/Unread

`POST /api-v3/notifications/notification/{notification_id}/{action}`

Marks a specific notification as read or unread for the current user.

Path parameters

notification_id – notification ID
action – read or unread

Curl (mark as read)

BASE_URL="https://<env-host>"
NOTIFICATION_ID=123

curl -sS -X POST "${BASE_URL}/api-v3/notifications/notification/${NOTIFICATION_ID}/read" \
  -H "Accept: application/json" \
  -H "Cookie: sessionid=<your-session-cookie>"

Curl (mark as unread)

BASE_URL="https://<env-host>"
NOTIFICATION_ID=123

curl -sS -X POST "${BASE_URL}/api-v3/notifications/notification/${NOTIFICATION_ID}/unread" \
  -H "Accept: application/json" \
  -H "Cookie: sessionid=<your-session-cookie>"

Response (simplified)

{
  "success": true,
  "message": "Notification marked as read successfully",
  "notification_data": {
    "notification_id": 123,
    "read_by": 456,
    "read_on": 1708000500,
    "read_by_name": "User Name",
    "read_by_username": "username",
    "notification_activities": []
  }
}

3. Notification Activity (list/readers)

`GET /api-v3/notifications/notification/activities`

Fetches notification records with activity information in a time window, including a limit_reached flag.

Query parameters

fromDate – start date (ISO string)
toDate – end date (ISO string)

Curl

BASE_URL="https://<env-host>"

curl -sS "${BASE_URL}/api-v3/notifications/notification/activities?fromDate=2026-03-01&toDate=2026-03-16" \
  -H "Accept: application/json" \
  -H "Cookie: sessionid=<your-session-cookie>"

4. Fetch Notification Types (Master + lab enable/disable)

`GET /api-v3/notifications/notification-type/all`

Returns all available notification types and their configuration.

Curl

BASE_URL="https://<env-host>"

curl -sS "${BASE_URL}/api-v3/notifications/notification-type/all" \
  -H "Accept: application/json" \
  -H "Cookie: sessionid=<your-session-cookie>"

Response (simplified)

{
  "total": 2,
  "notification_types": [
    {
      "id": 1,
      "category": "Report Ready",
      "name": "Organisation Report Ready",
      "description": "Organisation report is ready for review",
      "user_category": "org",
      "default_message_params": {},
      "order": 1,
      "is_disabled": false
    }
  ]
}

5. Lab notification type configuration (bulk)

`POST /api-v3/notifications/notification-type/bulk`

Bulk upsert/toggle lab-level enable/disable configuration for a set of notification types.

Request body

JSON body with notification_types, each containing:
- id (notification type id)
- is_disabled (boolean)

Curl

BASE_URL="https://<env-host>"

curl -sS -X POST "${BASE_URL}/api-v3/notifications/notification-type/bulk" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Cookie: sessionid=<your-session-cookie>" \
  -d '{
    "notification_types": [
      { "id": 1, "is_disabled": false },
      { "id": 2, "is_disabled": true }
    ]
  }'

6. User notification preferences

`GET /api-v3/notifications/notification-type/user-preferences/{labUserId}`

Returns the effective user preference flags for lab-enabled notification types.

Curl

BASE_URL="https://<env-host>"
LAB_USER_ID=12345

curl -sS "${BASE_URL}/api-v3/notifications/notification-type/user-preferences/${LAB_USER_ID}" \
  -H "Accept: application/json" \
  -H "Cookie: sessionid=<your-session-cookie>"

`POST /api-v3/notifications/notification-type/user-preferences`

Updates a user’s notification preferences (toggle enabled/disabled per type).

This endpoint expects form data:

labUserId – numeric id
userNotificationPreferences – JSON string of [{ "id": <typeId>, "is_disabled": 0|1 }, ...]

Curl

BASE_URL="https://<env-host>"

curl -sS -X POST "${BASE_URL}/api-v3/notifications/notification-type/user-preferences" \
  -H "Accept: application/json" \
  -H "Cookie: sessionid=<your-session-cookie>" \
  --data-urlencode "labUserId=12345" \
  --data-urlencode 'userNotificationPreferences=[{"id":1,"is_disabled":0},{"id":2,"is_disabled":1}]'

7. FCM topic subscription (web devices)

`POST /api-v3/notifications/fcm/topic/subscribe`

Subscribes a device token to topics derived from the user’s notification preferences and session context. Also creates/updates a row in FcmDevices.

Request body (JSON)

token (required)
device_id (optional)
platform (optional)

Curl

BASE_URL="https://<env-host>"

curl -sS -X POST "${BASE_URL}/api-v3/notifications/fcm/topic/subscribe" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Cookie: sessionid=<your-session-cookie>" \
  -d '{
    "token": "<fcm-token>",
    "device_id": "<browser-device-id>",
    "platform": "web"
  }'

`POST /api-v3/notifications/fcm/topic/unsubscribe`

Unsubscribes the token from all stored topics (from FcmDevices.topics) and deletes the corresponding FcmDevices row.

Curl

BASE_URL="https://<env-host>"

curl -sS -X POST "${BASE_URL}/api-v3/notifications/fcm/topic/unsubscribe" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Cookie: sessionid=<your-session-cookie>" \
  -d '{
    "token": "<fcm-token>"
  }'

8. Trigger a notification (server-to-server)

`POST /api-v3/notifications/{gateway}/{notification_type_id}/topic/notify`

Triggers a notification delivery for a specific notification type. This is commonly called by internal services/workers.

gateway: currently fcm
notification_type_id: numeric type id from NotificationTypesMaster (e.g. 1 for Org Report Ready, 2 for Critical Report)

Request body (JSON)

The body is the notification “context” used by the type implementation (examples include lab_id, org_id, lrr_id, etc.).

Curl

BASE_URL="https://<env-host>"

curl -sS -X POST "${BASE_URL}/api-v3/notifications/fcm/1/topic/notify" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Cookie: sessionid=<your-session-cookie>" \
  -d '{
    "lab_id": 1,
    "org_id": 100
  }'

9. Service worker (web)

`GET /api-v3/notifications/service-worker/firebase-sw.js`

Serves the Firebase service worker used to receive background push messages on web.

Curl

BASE_URL="https://<env-host>"

curl -sS "${BASE_URL}/api-v3/notifications/service-worker/firebase-sw.js" \
  -H "Accept: application/javascript"

10. Behavioural Notes

Security & auth
- All endpoints are protected by the standard authentication/session mechanisms of Crelio Health.
- Each call resolves the lab, organisation, and user from the current session.
Scoping
- Notification list and read/unread updates are always scoped to the current user.
- FCM subscribe/unsubscribe operates on the token bound to the current session and user preferences.
Limits
- List endpoints enforce limits (e.g. limit capped to 10000; activity list capped to 10000 with limit_reached flag).

For the underlying data structures backing these APIs, see Data Model.

API Reference

On this page