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 land in the bell dropdown and stay there until you mark them read.

Four kinds also send an email, because the bell alone isn't enough for them:

Kind	Who gets the email	Why
`access_request.created`	Every admin of the share's org	Someone is locked out and waiting on a decision.
`suggestion.submitted`	The share's owner	An unapproved suggestion is invisible to everyone except the owner, so a missed bell silently strands the suggester's work.
`suggestion.approved`	The suggester	They are usually an outside reviewer who was sent a link and has no reason to keep a dashboard open.
`suggestion.rejected`	The suggester	Same reason: without it they never learn whether their edit landed.

The pattern is the same one twice: mail the person who is waiting on someone else, and link them to wherever that waiting ends. A request and a pending suggestion link to where the decision is made (the inbox and that share's suggestions page); an approval links to the share, because the change is live and seeing it is the point. A rejection carries no link at all — there is nothing to click, and a button would imply otherwise.

Everything else is bell-only: a comment, for instance, is legible in place on the share, so it doesn't warrant a mail.

Email is best-effort and never gates the thing that triggered it — a bounced or undeliverable message can't cost you the access request or the suggestion. In a deployment with no mail provider configured, the bell still works and nothing errors.

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 — paginated list, supports unread_only=1 filter.
GET /api/v1/notifications/unread-count — bell-badge number.
POST /api/v1/notifications/read — 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 for the other kinds — only the four in the table above mail today, on the reasoning given there. The rest are bell-only.
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.