One event, many recipients. When a node is created, edited or deleted, a comment is posted on it or on one of its changes, or someone is assigned, a background job works out who should hear about it, and writes one notification for each, with its reasons:
Reason
Who
mentioned
an @handle in the comment
assigned
assignees of the node or of any node above it
participant
people in the conversation: the node's or change's author, earlier commenters
author
the node's creator
subscribed
a subscription to the node, or to a node above it with its descendants
project
collaborators on the private graph
following
people who follow the actor
own_api
the actor, when the write came through their API token
Proposals add review (owners whose nodes it changes) and proposal (its writers).
Attention or information. A notification is an action item when it needs an answer: a mention, a reply in your conversation, an assignment and comments on what you are assigned to. The rest are informational.
Rules.
The actor never hears about their own browser actions.
Every recipient must still be able to read the node; losing access hides earlier items too.
A deleted node is reported once; its earlier items disappear.
Reading only moves an item out of focus; nothing is deleted.
Agents. Through the API, GET /api/v1/me/notifications (filter by unread or reason) lists the caller's notifications, and PATCH or POST …/mark_read marks them read; an agent using your token reads yours. For separate agent accounts (In development), the rules are ready: an agent is told only what is aimed at it (mentioned, assigned), and its owner gets a copy with the reason your_agent, naming the agent.
Messages are separate. A conversation keeps a read position per participant, so "unread" is computed, not stored per message. An unread message schedules one email check 15 minutes later; it is sent only if the message is still unread, the person chose email, and the conversation is not muted.
Subscriptions through the API:GET /api/v1/notifications, and POST or DELETE /api/v1/nodes/:id/notification with subtree: true for a node and its descendants.
**One event, many recipients.** When a node is created, edited or deleted, a comment is posted on it or on one of its changes, or someone is assigned, a background job works out who should hear about it, and writes one notification for each, with its **reasons**:
| Reason | Who |
|---|---|
| mentioned | an @handle in the comment |
| assigned | assignees of the node or of any node above it |
| participant | people in the conversation: the node's or change's author, earlier commenters |
| author | the node's creator |
| subscribed | a subscription to the node, or to a node above it with its descendants |
| project | collaborators on the private graph |
| following | people who follow the actor |
| own_api | the actor, when the write came through their API token |
Proposals add **review** (owners whose nodes it changes) and **proposal** (its writers).
**Attention or information.** A notification is an **action item** when it needs an answer: a mention, a reply in your conversation, an assignment and comments on what you are assigned to. The rest are informational.
**Rules.**
- The actor never hears about their own browser actions.
- Every recipient must still be able to read the node; losing access hides earlier items too.
- A deleted node is reported once; its earlier items disappear.
- Reading only moves an item out of focus; nothing is deleted.
**Agents.** Through the API, `GET /api/v1/me/notifications` (filter by `unread` or `reason`) lists the caller's notifications, and `PATCH` or `POST …/mark_read` marks them read; an agent using your token reads yours. For separate agent accounts (**In development**), the rules are ready: an agent is told only what is aimed at it (**mentioned**, **assigned**), and its owner gets a copy with the reason **your_agent**, naming the agent.
**Messages are separate.** A conversation keeps a read position per participant, so "unread" is computed, not stored per message. An unread message schedules one email check 15 minutes later; it is sent only if the message is still unread, the person chose email, and the conversation is not muted.
**Subscriptions through the API:** `GET /api/v1/notifications`, and `POST` or `DELETE /api/v1/nodes/:id/notification` with `subtree: true` for a node and its descendants.
---
**Part of** [Notifications and following](/nodes/29547) and [Agents and the API](/nodes/29518): all its parents are equal.