---
name: notifications
description: In-app notifications — bell-icon dropdown, kinds, and the mark-read flow.
---

# Notifications

Every dashboard surface has a bell icon in the top bar. The badge shows your unread count; the dropdown lists the most recent notifications and a "Mark all read" action. There is no email digest yet — notifications live in the app.

## What triggers a notification

| Trigger | Notification kind |
| ------- | ----------------- |
| Someone comments on a share you own | `comment.created` |
| A visitor requests access to one of your shares | `access_request.created` |
| Your access request is approved | `access_request.approved` |
| Your access request is denied | `access_request.denied` |
| A suggested-change version lands on a share you own | `suggestion.submitted` |
| Your suggested change is approved | `suggestion.approved` |
| Your suggested change is rejected | `suggestion.rejected` |
| You are added as an org admin | `member.added_to_org` |
| You are added to a project as viewer or editor | `member.added_to_project` |
| You are granted editor access on a single share | `member.added_to_share` |

Notifications never email you. They land in the bell dropdown and stay there until you mark them read.

## Self-actions don't notify

The `comment.created` notification skips the actor when the actor is also the share owner — commenting on your own share doesn't notify you of your own comment. Other kinds attribute to the deciding admin, not the affected user (e.g. when an admin approves an access request, the requester sees `access_request.approved`; the admin does not see their own action as a notification).

## Marking read

Three ways to mark read:

- **Click an individual item** in the dropdown — opens its link and marks just that row.
- **"Mark all read"** at the bottom of the dropdown — flips every unread row.
- **Auto-mark on dashboard visit** — opening `/dashboard` clears the count badge for new visitors; the dropdown still shows recent items.

## API

If you want to wire notifications into another surface (a Slack bot, a Raycast script, your own dashboard), see the API reference:

- [`GET /api/v1/notifications`](/docs/api#endpoints--notifications) — paginated list, supports `unread_only=1` filter.
- [`GET /api/v1/notifications/unread-count`](/docs/api#endpoints--notifications) — bell-badge number.
- [`POST /api/v1/notifications/read`](/docs/api#endpoints--notifications) — mark specific ids read, or `{all: true}` to flip everything.

All three require an authenticated user (cookie session or per-user CLI token). There is no operator-bearer fallback — notifications are user-scoped.

## What's not in here

- **Email delivery** of notifications — deferred.
- **Per-kind opt-out preferences** — deferred. Every kind fires for every user today.
- **Push notifications** to the browser or a mobile app — deferred.
- **Anonymous-suggester notification** — anon suggestions are gated behind V4 #20 (captcha + rate-limit) and don't fire today.

When any of these land, they will reuse the same `notifications` table — the API shape above is the long-term surface.