Notifications API #
The notification list is backed by the SQLite feed index that the firehose
consumer maintains (internal/firehose/notifications.go). The JSON endpoint is
read-only: it never changes read state, so a client can poll the list for a badge
without silently clearing it (HandleNotificationsJSON). Marking read is a
separate call.
GET /api/notifications #
Authentication required. Query parameters:
| Param | Type | Default | Description |
|---|---|---|---|
cursor |
string |
— | Opaque page cursor: pass the previous response's next_cursor verbatim. |
| — | — | — | Page size is fixed at 30 (notificationsPerPage). There is no limit parameter. |
Response #
{
"notifications": [
{
"id": "1731670000000000000",
"type": "like",
"actor_did": "did:plc:xyz",
"subject_uri": "at://did:plc:abc123/social.oolong.alpha.brew/3kbrew",
"created_at": "2026-11-16T12:00:00Z",
"read": false,
"actor_handle": "bob.test",
"actor_display_name": "Bob",
"actor_avatar": "https://cdn.bsky.app/...",
"link": "/brews/did:plc:abc123/3kbrew",
"action_text": "liked your tea brew"
}
],
"next_cursor": ""
}
| Field | Type | Description |
|---|---|---|
notifications |
array |
Newest first. Always [] when empty. |
notifications[].id |
string |
Stable notification id (timestamp-based). |
type |
string |
like, comment, or comment_reply. |
actor_did |
string |
Who performed the action. |
subject_uri |
string |
The record that was acted on. |
created_at |
string |
RFC 3339 timestamp. |
read |
bool |
Read flag at the time of the query. |
actor_handle |
string |
Cached handle, or the actor DID when the profile is unknown. |
actor_display_name |
string |
Empty when unset or unknown. |
actor_avatar |
string |
Empty when unset or unknown. |
link |
string |
Local direct link (/{collection_path}/{did}/{rkey}); empty when the subject collection has no route. |
action_text |
string |
Display string: liked your …, commented on your …, replied to your comment. |
next_cursor |
string |
Cursor for the next page; empty at the end. |
The entity noun inside action_text comes from the app's entity routes, so a
custom app label changes that text, not the field set. link uses the owner's
DID, not their handle, so it keeps working when a handle changes.
A user with no notifications, or a deployment without a feed index, gets
{"notifications": [], "next_cursor": ""} with status 200 — not an error.
Errors #
| Status | Code | When |
|---|---|---|
| 401 | authentication_required |
No session. |
| 500 | internal_error |
The feed index query failed. |
POST /api/notifications/read #
Marks all notifications read for the viewer. There is no per-notification variant, and no body is read.
{"read": true}
The answer is always this body; there is no redirect variant. Cross-site posts
are rejected by CSRF protection (403 permission_denied).
| Status | Code | When |
|---|---|---|
| 401 | authentication_required |
No session. |
| 500 | internal_error |
The write failed. |
The unread count #
GET /api/session exposes unread_notifications; that is the badge number, and
reading the notification list does not change it.
Page behavior #
/notifications is a Solid page that calls the two endpoints above.
Accept: application/json on the page route returns the same list as
GET /api/notifications (routing.SPAOrJSON). A GET never clears the badge;
the page marks read with POST /api/notifications/read once the list is shown.
Coverage #
internal/handlers/notifications_json_test.go covers the auth requirement, the
empty-list shape, read-only behaviour, store failure (500), mark-read JSON with
and without a JSON Accept header, and mark-read auth/store failures. The E2E
fixture has no feed index, so it only exercises the empty-list path.