HelpBlog
Features
About
Login
Sign Up

Help

Notifications

Notifications are generated server-side for events like new followers, incoming replies, and I Dig! reactions. The notification tray is the main consumer.

Endpoint table

MethodPathAuthDescription
GET/api/notificationsSession or BearerNotifications. ?scope=tray returns the unread tray; omitting scope returns the historical read + unread feed. Both return { unreadCount, items }.
GET/api/notifications/:idSession or BearerGet a single notification by ID.
DELETE/api/notifications/:idSession or BearerDelete a notification.
PATCH/api/notifications/:id/readSession or BearerMark one notification read (idempotent). Returns { ok: true }.
POST/api/notifications/mark-all-readSession or BearerMark all unread notifications read. Returns { ok: true, updated: N }.
GET/api/user/notification-preferencesSession or BearerPer-event channel preferences. Returns { events: [ ... ] }.
PATCH/api/user/notification-preferencesSession or BearerToggle channels for one event. Body: { key, channels }. Returns the updated event.

Notification object

FieldTypeDescription
idstringUnique notification ID.
titlestringShort heading (e.g. "New follower").
bodystringFull notification text.
actionUrlstring | nullRelative URL to navigate to when clicked (e.g. /profile/someuser).
typestring | nullCategory string (e.g. "follow", "dig", "reply").
metadataobjectArbitrary structured data attached by the server.
createdAtstring (ISO 8601)When the notification was created.
readAtstring | nullWhen it was read; null if still unread.
routePathstring | nullClient-navigable in-app path derived by the server (e.g. /message/{id}/thread, /user/{username}, /lists/{id}, /organizations/{ref}). null when no safe path can be resolved. Always present.
targetobjectTyped IDs relevant to the notification: { messageId, listId, orgId }, each string or null. Always present.

Fetching the tray

GET /api/notifications?scope=tray

{
  "unreadCount": 3,
  "items": [
    {
      "id": "notif_abc001",
      "title": "New follower",
      "body": "someuser started following you.",
      "actionUrl": "/profile/someuser",
      "type": "follow",
      "metadata": {},
      "createdAt": "2025-06-11T10:00:00.000Z",
      "readAt": null,
      "routePath": "/user/someuser",
      "target": { "messageId": null, "listId": null, "orgId": null }
    }
  ]
}

unreadCount is the total count across all unread notifications. In tray mode, items contains up to the user's configured tray limit (default 20, clamped to 10–40) of the most recent unread items. Omitting scope is not an error: it returns the historical feed (both read and unread rows, newest first) instead, using ?limit= (1–50, default 20); both modes return 200.

Marking notifications read

Mark a single notification read (safe to call multiple times):

PATCH /api/notifications/notif_abc001/read

Response (200): { "ok": true }

Mark all unread notifications read at once:

POST /api/notifications/mark-all-read

Response (200): { "ok": true, "updated": 3 }. updated is the count of notifications that were changed from unread to read.

Deletion

DELETE /api/notifications/notif_abc001

Deletes the notification entirely (rather than just marking it read). The action is irreversible.

Notification preferences

Preferences enable or disable individual delivery channels per event.

Preferences cover only the events the server actually emits, and only the channels each event supports. Not every event supports every channel: the supported channels are one of push, inApp, and email, and vary per event as listed below. Do not assume all three channels are present on every event.

Event keyChannelsCovers
digpush, inAppDigs on your messages.
pushpush, inAppPushes (reposts) of your messages, with or without commentary.
followpush, emailNew followers and follow requests.
mentionemailWhen someone @-mentions you in a message.
replyemailWhen someone replies to your message.

When a user has never set a preference, every channel defaults to enabled. Toggling a channel off suppresses that delivery channel for that event.

Get preferences

GET /api/user/notification-preferences

{
  "events": [
    { "key": "dig",     "label": "Digs on your messages",         "description": "...", "channels": { "push": true, "inApp": true } },
    { "key": "push",    "label": "Pushes of your messages",       "description": "...", "channels": { "push": true, "inApp": true } },
    { "key": "follow",  "label": "New followers & follow requests","description": "...", "channels": { "push": true, "email": true } },
    { "key": "mention", "label": "Mentions",                      "description": "...", "channels": { "email": true } },
    { "key": "reply",   "label": "Replies",                       "description": "...", "channels": { "email": true } }
  ]
}

Each event's channels object contains only the keys that event supports (e.g. follow has no inApp key; mention and reply expose only email).

Update one event

PATCH /api/user/notification-preferences
Content-Type: application/json

{ "key": "dig", "channels": { "push": false, "inApp": true } }

Returns the updated single event object:

{
  "key": "dig",
  "label": "Digs on your messages",
  "description": "...",
  "channels": { "push": false, "inApp": true }
}

Returns 400 for an unknown key, a missing/invalid channels object, a channel not supported by that event (e.g. inApp for follow, or push for mention), a non-boolean channel value, or when no valid channels are provided.