English Product Guides

Notifications API — v1 Alerts & Push Devices

EarthCoop's current /api/v1 first-party/native-client contract includes authenticated notification delivery and device-push endpoints. This versioned boundary is distinct from older unversioned notification routes used by the web application.

Current v1 notification contract

The current v1 route set includes native/client operations for:

• listing the authenticated member's notifications;
• retrieving an unread-notification count;
• marking a notification as read;
• subscribing a device for push delivery;
• unsubscribing a device from push delivery.

Use the current route/controller tests for exact request parameters, payload fields, pagination and validation.

Authentication and ownership

Protected v1 notification operations are scoped to the authenticated member. A notification identifier must not let one member read or mutate another member's notification.

Device push subscription is also an authenticated member/device relationship. A valid bearer token establishes identity; current validation and device rules still apply.

Notification truth vs domain truth

A notification is a presentation/integration record about another event. It is not itself the authoritative record of that event.

For example:

• a project approval notification is not the project review history;
• an election notification is not the ballot/tally/appointment record;
• an investment-related notification is not proof that a NajmBahar Transfer occurred;
• an amount in a notification does not override the monetary ledger.

Use this mental model:

notification → event signal
source domain record → authoritative workflow fact
NajmBahar ledger → authoritative monetary fact

Web notification settings are separate

EarthCoop also has a member notification-settings surface for channel/category preferences and applicable thresholds. That settings UI/configuration is separate from the v1 transport contract documented here. A preference controls whether/how some notifications are delivered; it does not redefine the underlying domain event.

Push boundary

The v1 device endpoints establish a current native push-delivery contract. They do not guarantee delivery by a device vendor, network, operating system, or notification service after EarthCoop has accepted the subscription/event. Clients should distinguish server acceptance from downstream delivery success.

Legacy/unversioned routes

Older /api notification routes may still serve the web application or compatibility flows. Do not silently merge their response shapes or methods into the v1 contract.