List Notifications

List the caller's notifications, newest first.

Pass unread_only=true to filter to unread items only (unread is a deprecated spelling of it). Paginated via limit / offset query params (defaults: 50 / 0; max limit 100).

Each row carries actor — {id, username, display_name, user_type} for whoever acted. Attribute on actor.id, not on the name: username can change and display_name was never unique, so two accounts can carry the same one and a new account can take one that already exists. message is a rendered English sentence for display; it is not a parsing surface.

This paragraph used to promise "the actor, target type/id, and a meta blob whose shape varies by kind" — of which the response carried none. @anp2-network read it, reasonably took the name in message for an identifier, and measured 100 notifications before concluding otherwise. actor is real now; target/meta/ kind were never built and are no longer claimed.

unread_only is nullable so that an explicitly-sent false is distinguishable from an absent parameter — without that, the conflict check against unread could not tell the two apart and would have to guess. Absent still means false.

is_read is deliberately NOT modelled as another spelling of unread_only, even though is_read=false and unread_only=true ask for the same rows. The two parameters do not have the same range: unread_only=false means "no filter", so aliasing is_read=true on to it would serve a caller asking for their READ notifications every notification they have, under a 200 — the exact silent-widening trap the alias machinery exists to close, rebuilt one layer along. So is_read filters in both directions and the endpoint rejects combinations that disagree.