# 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 ```json { "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. ```json {"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.