fep

FEP-34ec: Notification Collection Endpoint

Summary

This FEP defines a standardized notification collection for ActivityPub actors. A new notifications property under endpoints (ActivityPub §5.7) provides an OrderedCollection containing references to activities that the server deems notification-worthy. Unlike the inbox, which serves as the delivery channel for all incoming activities, the notification collection is a curated subset — engagement-oriented events such as likes, mentions, and boosts. Dismissal of notifications uses the standard Remove activity (ActivityPub §7.5). Batch dismissal is supported via FEP-db70 (RemoveAll) with optional FEP-34c1 filtering.

Motivation

ActivityPub defines an inbox as the primary collection for incoming activities. However, clients need to distinguish between content-oriented activities (home feed) and engagement-oriented events (notifications) — a separation that SWICG #21 has long called for.

Today, every Fediverse software (Mastodon, Pleroma, GoToSocial, Misskey) implements notifications as a proprietary REST API without interoperability. There is no standardized ActivityPub endpoint for notifications.

This FEP closes this gap by defining:

No new types or vocabulary beyond the notifications endpoint property are introduced. The collection holds references to existing activities — the activity types themselves provide categorization.

Specification

1. Notification Endpoint on the Actor

A conforming server MUST provide the notifications property under endpoints in the actor object:

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://w3id.org/fep/34ec"
  ],
  "type": "Person",
  "id": "https://example.com/actors/bob",
  "endpoints": {
    "sharedInbox": "https://example.com/inbox",
    "notifications": "https://example.com/actors/bob/notifications"
  }
}

The notifications property points to an OrderedCollection sorted by server receive time in descending order (newest first).

2. Collection Contents

The notification collection contains references to activities that the server considers notification-worthy for the actor. These are typically engagement-oriented events:

Activity Type Typical Condition
Like Object is owned by the actor
Announce Object is owned by the actor
Create Actor is mentioned (to/cc/tag)
Follow Actor is the follow target
Update Object is owned by or observed by the actor

This table is non-normative. Servers MAY include any activity type and SHOULD apply their own criteria for what constitutes a notification.

The activities referenced in the notification collection also remain in the actor’s inbox. The notification collection is a view, not a separate delivery mechanism.

3. Collection Semantics

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://w3id.org/fep/34ec"
  ],
  "type": "OrderedCollection",
  "id": "https://example.com/actors/bob/notifications",
  "totalItems": 3,
  "orderedItems": [
    "https://alice.example/activities/like-123",
    "https://carol.example/activities/create-456",
    "https://dave.example/activities/announce-789"
  ]
}

Servers MAY inline the full activity objects instead of providing only IRIs. When inlining, the standard Activity Streams representation is used — no wrapper type is needed:

{
  "type": "OrderedCollection",
  "id": "https://example.com/actors/bob/notifications",
  "totalItems": 2,
  "orderedItems": [
    {
      "type": "Like",
      "id": "https://alice.example/activities/like-123",
      "actor": "https://alice.example/actors/alice",
      "object": "https://example.com/posts/post-1",
      "published": "2026-02-24T10:00:00Z"
    },
    {
      "type": "Create",
      "id": "https://carol.example/activities/create-456",
      "actor": "https://carol.example/actors/carol",
      "object": {
        "type": "Note",
        "content": "Hey @bob, check this out!"
      },
      "published": "2026-02-24T09:30:00Z"
    }
  ]
}

4. Pagination

The collection SHOULD support OrderedCollectionPage pagination. Since the collection only contains pending notifications, it typically remains small. Pagination becomes relevant only with larger volumes.

{
  "type": "OrderedCollection",
  "id": "https://example.com/actors/bob/notifications",
  "totalItems": 150,
  "first": "https://example.com/actors/bob/notifications?page=1"
}

5. C2S Operations

5.1 Dismiss a Single Notification (Remove)

A client dismisses a notification by posting a Remove activity to the actor’s outbox, as defined in ActivityPub §6.11:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Remove",
  "actor": "https://example.com/actors/bob",
  "object": "https://alice.example/activities/like-123",
  "target": "https://example.com/actors/bob/notifications"
}

The server MUST remove the activity reference from the notification collection. The activity itself MUST NOT be deleted from the inbox.

5.2 Batch Dismiss (RemoveAll)

Batch dismissal is supported via FEP-db70 (RemoveAll). An optional FEP-34c1 filter can be provided to dismiss only matching notifications.

Dismiss all notifications (“mark all as read”):

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://w3id.org/fep/db70"
  ],
  "type": "RemoveAll",
  "actor": "https://example.com/actors/bob",
  "target": "https://example.com/actors/bob/notifications"
}

Dismiss all notifications of a specific type (with FEP-34c1 filter):

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://w3id.org/fep/db70",
    "https://w3id.org/fep/34c1",
    "https://w3id.org/tree"
  ],
  "type": "RemoveAll",
  "actor": "https://example.com/actors/bob",
  "target": "https://example.com/actors/bob/notifications",
  "filter": {
    "type": "FilterRequest",
    "relation": [
      {
        "type": "EqualToRelation",
        "path": { "@id": "as:type" },
        "value": { "@id": "as:Like" }
      }
    ]
  }
}

Dismiss all notifications older than a given date:

{
  "type": "RemoveAll",
  "actor": "https://example.com/actors/bob",
  "target": "https://example.com/actors/bob/notifications",
  "filter": {
    "type": "FilterRequest",
    "relation": [
      {
        "type": "LessThanRelation",
        "path": { "@id": "as:published" },
        "value": { "@value": "2026-02-17T00:00:00Z", "@type": "xsd:dateTime" }
      }
    ]
  }
}

The server MUST remove all activity references matching the filter from the notification collection. Without a filter, the server MUST remove all activity references.

6. Collection Filtering (Read)

Conforming servers SHOULD support FEP-34c1 filtering for the notification collection. The activity type SHOULD be accepted as a tree:path for filtering.

The server signals filter support via tree:search in the collection:

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://w3id.org/fep/34ec",
    "https://w3id.org/fep/34c1",
    "https://w3id.org/tree"
  ],
  "type": "OrderedCollection",
  "id": "https://example.com/actors/bob/notifications",
  "totalItems": 25,
  "tree:search": {
    "type": "FilterEndpoint",
    "template": "https://example.com/actors/bob/notifications/filter"
  }
}

A client retrieving only Like notifications sends a POST to the filter endpoint:

Request: POST https://example.com/actors/bob/notifications/filter

{
  "@context": [
    "https://w3id.org/fep/34c1",
    "https://w3id.org/tree"
  ],
  "type": "FilterRequest",
  "relation": [
    {
      "type": "EqualToRelation",
      "path": { "@id": "as:type" },
      "value": { "@id": "as:Like" }
    }
  ],
  "pageSize": 20
}

Response:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "OrderedCollectionPage",
  "partOf": "https://example.com/actors/bob/notifications",
  "totalItems": 5,
  "orderedItems": [
    {
      "type": "Like",
      "id": "https://alice.example/activities/like-123",
      "actor": "https://alice.example/actors/alice",
      "object": "https://example.com/posts/post-1",
      "published": "2026-02-24T10:00:00Z"
    }
  ]
}

7. Authorization

The notification collection MUST only be accessible to the authenticated actor. Unauthenticated requests MUST be rejected with 401 Unauthorized.

Security Considerations

Conformance

A conforming server MUST:

A conforming server SHOULD:

Implementations

References

CC0 1.0 Universal (CC0 1.0) Public Domain Dedication

To the extent possible under law, the authors of this Fediverse Enhancement Proposal have waived all copyright and related or neighboring rights to this work.