Notifications — URLs

Overview

The notifications.urls module defines the API endpoints exposed by the notifications app.

These endpoints are grouped by responsibility:

• notification read endpoints (inbox)
• notification action endpoints (mutations)
• push device endpoints
• registry metadata endpoint

All endpoints are designed to be:

• org-scoped (where applicable)
• REST-like
• consistent in naming and structure

---

Base path

All endpoints are typically mounted under:

/notifications/

Example:

/api/notifications/

---

Endpoint groups

Notification read endpoints

These endpoints provide access to the user’s notification inbox.

Method	Path	View	Description
GET	/notifications/unread-count/	UnreadCountView	Get unread notification count
GET	/notifications/	MyNotificationsView	Main notification feed
GET	/notifications/ungrouped/	NotificationUngroupedView	Ungrouped notifications only

---

Notification action endpoints

These endpoints mutate notification state.

Method	Path	View	Description
POST	/notifications/mark-all-read/	MarkAllReadView	Mark all notifications as read
POST	/notifications/mark-read//	MarkNotificationReadView	Mark a single notification as read
POST	/notifications/bulk-mark-read/	BulkMarkReadView	Mark multiple notifications as read
POST	/notifications/clear//	ClearNotificationView	Clear a single notification
POST	/notifications/clear-group/	ClearNotificationGroupView	Clear notifications by group_key
POST	/notifications/clear-read/	ClearReadNotificationsView	Clear all read notifications

---

Push device endpoints

These endpoints manage push notification device tokens.

Method	Path	View	Description
POST	/notifications/push-devices/upsert/	UpsertPushDeviceView	Register or update a device
POST	/notifications/push-devices/deactivate/	DeactivatePushDeviceView	Deactivate a device
POST	/notifications/push-devices/ping/	PingPushDeviceView	Heartbeat for device activity

---

Registry endpoint

This endpoint exposes notification configuration metadata.

Method	Path	View	Description
GET	/notifications/registry/	NotificationRegistryMetaView	Get notification rules metadata

---

Query parameters

Notification feed

Supported query parameters for /notifications/:

• after
• ISO datetime string
• returns only notifications updated after this timestamp

• used for incremental sync

• collapsed

• values: "1", "true", "True"
• enables grouped notification response

---

URL design principles

Consistency

• plural resources (notifications, push-devices)
• action-based endpoints for mutations (mark-read, clear)

---

Clear separation of concerns

• read endpoints use GET
• mutation endpoints use POST
• device management is grouped separately

---

Org scoping

Most endpoints require:

• authenticated user
• valid org context (HasCurrentOrg)

This ensures:

• multi-tenant isolation
• safe access patterns

---

Predictable naming

• mark-read → update read state
• clear → soft delete
• upsert → create or update
• ping → heartbeat

---

Example usage

Get notifications

GET /notifications/

---

Get unread count

GET /notifications/unread-count/

---

Mark notification as read

POST /notifications/mark-read//

---

Register push device

POST /notifications/push-devices/upsert/

Body:

{ "provider": "expo", "token": "ExponentPushToken[...]" }

---

Get registry metadata

GET /notifications/registry/

---

Versioning considerations

The current URL structure is:

• flat
• versionless

If versioning is introduced, endpoints should be prefixed:

/api/v1/notifications/

---

Summary

The notifications.urls module defines a clear and consistent API surface.

It provides endpoints for:

• reading notifications
• mutating inbox state
• managing push devices
• exposing notification metadata

This structure keeps the API:

• intuitive
• scalable
• frontend-friendly