Skip to main content

Notifications API

The Notifications namespace provides operations for retrieving activity notifications, tracking read state, and getting badge counts.

See Notifications concept doc for product-level details.

Key Endpoints​

List notifications - GET /notifications

Get notification status - GET /notifications/status

Mark notification as read - POST /notifications/{id}/mark-read

Mark all as read - POST /notifications/mark-all-read

Common Workflows​

Get All Notifications​

GET /notifications

Returns all your notifications across all spaces, ordered by most recent activity.

Response structure:

{
  "items": [
    {
      "id": "notification_abc123",
      "type": "notify.post.created",
      "space": {
        "id": "space_xyz",
        "did": "did:dfos:...",
        "displayName": "Dark Forest Collective"
      },
      "readState": "unread",
      "scope": {
        "type": "post",
        "preview": {
          "id": "post_123",
          "title": "Welcome!",
          "createdBy": { "did": "...", "displayName": "Alice" },
          "createdAt": "2025-01-23T10:00:00.000Z"
        }
      },
      "aggregation": null,
      "firstActivityAt": "2025-01-23T10:00:00.000Z",
      "lastActivityAt": "2025-01-23T10:00:00.000Z",
      "lastReadAt": null,
      "createdAt": "2025-01-23T10:00:00.000Z"
    }
  ],
  "totalCount": 15
}

Filter Notifications by Space​

GET /notifications?spaceDID=space_xyz

Get notifications for a specific space only.

Get Notification Status (Badge Counts)​

GET /notifications/status

Returns global notification status including last activity timestamp and total unread count. Perfect for notification badges.

Response:

{
  "lastActivityAt": "2025-01-23T15:30:00.000Z",
  "lastNotificationId": "notification_xyz789",
  "unreadCount": 5
}

Mark Notification as Read​

POST /notifications/notification_abc123/mark-read

Mark a single notification as read. Updates readState to "read" and sets lastReadAt timestamp.

Mark All Notifications as Read​

POST /notifications/mark-all-read

Mark all your notifications as read at once. Optionally filter to a specific space:

POST /notifications/mark-all-read
{
  "spaceDID": "space_xyz"
}

Understanding Aggregation​

Grouped notifications include an aggregation field with sample items and total count.

Example aggregated notification (multiple people reacted):

{
  "type": "notify.post.reaction.added",
  "scope": {
    "type": "post",
    "preview": {
      "id": "post_123",
      "title": "Project Update"
    }
  },
  "aggregation": {
    "type": "identity",
    "items": [
      { "did": "...", "displayName": "Alice" },
      { "did": "...", "displayName": "Bob" },
      { "did": "...", "displayName": "Carol" }
    ],
    "totalCount": 12
  }
}

This means "12 people reacted to your post (showing 3 most recent: Alice, Bob, Carol)."

Types of aggregation:

  • identity - Aggregates people (reactions, member joins)
  • post - Aggregates posts (multiple new posts in a space)

Notification Types​

Different type values indicate different activities:

Content:

  • notify.post.created - New post
  • notify.post.pinned - Post pinned (admins only)
  • notify.post.comment.added - New comment
  • notify.post.reaction.added - Reaction on post
  • notify.comment.reaction.added - Reaction on comment

Members:

  • notify.member.joined - New member
  • notify.member.role_changed - Role change
  • notify.member.kicked - Member removed (admins only)
  • notify.member.banned - Member banned (admins only)

Applications:

  • notify.application.submitted - New application (admins only)
  • notify.application.approved - Application approved (applicant only)
  • notify.application.rejected - Application rejected (applicant only)
  • notify.application.canceled - Application withdrawn (admins only)

Polling Strategy​

Notifications are pull-based. Recommended polling:

  1. Active use: Poll every 10-30 seconds
  2. Background: Poll every 1-5 minutes
  3. Use badge count endpoint (/notifications/status) for frequent checks (lighter weight)
  4. Use full list endpoint when displaying notification feed

Efficient polling:

# Quick badge check (lightweight)
GET /notifications/status

# Full feed when user opens notifications
GET /notifications

Authorization​

  • Listing notifications: Your own notifications only
  • Marking read: Your own notifications only
  • Visibility: Notifications respect space membership and role permissions

See Also​