Notifications

Manage notification preferences, read state, and retrieve notifications for the authenticated user.

Endpoints

List notifications for the authenticated user

Scope

notifications:read

Parameters

unreadstringSet to "true" to filter to unread notifications only

limitnumberNumber of notifications (max 100, default 50)

offsetnumberPagination offset (max 10000, default 0)

Response

{
  "notifications": [
    {
      "id": "ntf_abc123",
      "type": "comment",
      "title": "New comment",
      "body": "Jane commented on your post",
      "read": false,
      "resourceType": "post",
      "resourceId": "pst_xyz789",
      "createdAt": 1706795400000,
      "actor": {
        "id": "usr_def456",
        "name": "Jane Smith",
        "image": "/api/media/avatars/jane.jpg"
      }
    }
  ],
  "total": 42,
  "hasMore": true
}

Get count of unread notifications

Scope

notifications:read

Mark all notifications as read

Scope

notifications:write

Update a notification (mark read/unread)

Scope

notifications:write

Parameters

idstringrequiredNotification ID (URL path)

readbooleanrequiredMark as read (true) or unread (false)

Get notification preferences

Scope

notifications:read

Update notification preferences

Scope

notifications:write

Parameters

emailNewCommentbooleanEmail on new comments

emailNewReactionbooleanEmail on new reactions

emailNewPostbooleanEmail on new posts

emailMentionbooleanEmail on mentions

emailDigestbooleanEmail digest notifications

emailTeamActivitybooleanEmail on team activity

pushNewCommentbooleanPush on new comments

pushNewReactionbooleanPush on new reactions

pushNewPostbooleanPush on new posts

pushMentionbooleanPush on mentions

pushTeamActivitybooleanPush on team activity

inAppNewCommentbooleanIn-app on new comments

inAppNewReactionbooleanIn-app on new reactions

inAppNewPostbooleanIn-app on new posts

inAppMentionbooleanIn-app on mentions

inAppTeamActivitybooleanIn-app on team activity

globalMutebooleanMute all notifications

quietHoursEnabledbooleanEnable quiet hours

quietHoursStartstringQuiet hours start time (HH:MM)

quietHoursEndstringQuiet hours end time (HH:MM)

quietHoursTimezonestringQuiet hours timezone (e.g. America/New_York)

Offset-based Pagination

The notifications endpoint uses offset-based pagination. Use the offset and limit query parameters to paginate through results. The response includes a total count and hasMore flag.

Notification Preferences

Preferences are configured using flat boolean fields, prefixed by channel (email, push, inApp) and event type. Additional fields control global mute and quiet hours.

email*emailNewComment, emailNewReaction, emailNewPost, emailMention, emailDigest, emailTeamActivity

push*pushNewComment, pushNewReaction, pushNewPost, pushMention, pushTeamActivity

inApp*inAppNewComment, inAppNewReaction, inAppNewPost, inAppMention, inAppTeamActivity

globalglobalMute, quietHoursEnabled, quietHoursStart, quietHoursEnd, quietHoursTimezone