Notifications
Notifications inform you about activity in your projects — agent questions awaiting your response, completed background tasks, errors, and other system events.
Document activity in your projects
Section titled “Document activity in your projects”A project’s knowledge base is shared, so a document landing in it is project news. Four event keys cover the document lifecycle:
| Event key | When it fires | Default | Can you turn it off? |
|---|---|---|---|
document.uploaded |
a member uploads a document (POST /api/documents/upload, and once per request for /upload/batch) |
on | yes |
document.version_synced |
a data-source sync appends a new version of a document (a source’s first ingest does not notify) | on | yes |
document.extraction_completed |
extraction finished and its objects were merged into the graph | on | yes |
document.processing_failed |
an upload’s parsing or extraction reached its final retry (dead letter) | on | no |
Who receives them
Section titled “Who receives them”Every row goes to the project’s members except the member whose action produced it — you are never notified about your own upload or your own extraction run. A data-source sync carries no actor, so a new version it appends reaches every member, including whoever pressed sync. Consequences worth knowing:
- A solo project sees nothing from the three informational keys; there is nobody else to tell.
- A batch upload arrives as one digest row (
12 documents uploaded · a.pdf, b.pdf, c.pdf and 9 more) instead of one row per file. - An extraction that leaves objects on a staging branch for review sends
extraction.review_ready, notdocument.extraction_completed— one row per extraction outcome, never both.
document.processing_failed is the exception to the actor rule: it is not
suppressed for the person whose run failed, because that person is the one who has
to act. It fires once, on the final attempt (retries do not notify), and names the
stage that failed — Text extraction or Extraction.
Turning them off
Section titled “Turning them off”Project notification preferences are per user and per project:
GET /api/notifications/preferences?project_id=<project>PUT /api/notifications/preferencesContent-Type: application/json
{ "projectId": "<project>", "eventKey": "document.uploaded", "enabled": false }The three informational document keys are on by default and are reported with
enabled: true before you save anything, so you disable what you do not want
rather than opting into each key. document.processing_failed is required
delivery (required: true): a stored preference for it is ignored when the row is
created, because a processing run that died needs someone to look at it.
Notification fields
Section titled “Notification fields”| Field | Description |
|---|---|
title |
Short heading |
message |
Full notification body |
severity |
info · warning · error · success |
importance |
important · other |
category |
Optional grouping label |
relatedResourceType |
The type of resource this notification relates to |
relatedResourceId |
UUID of the related resource |
actionUrl |
Optional deep link to the relevant UI page |
actionLabel |
Button label for the action link |
read |
Whether you have read the notification |
dismissed |
Whether you have dismissed it |
expiresAt |
Optional auto-expiry timestamp |
The web inbox
Section titled “The web inbox”The bell in the top bar counts unread notifications for the scope on screen, and the inbox offers three scopes:
| Scope | Shows |
|---|---|
| Everything (default) | account events and project activity from every project you belong to |
| Account | account-scope events only — membership, permissions, invites, budget |
| Project | the active project only |
Everything is the default for the inbox and for the bell on every other page, so a teammate’s upload raises the bell while you are elsewhere in the app. In Everything and Account the list can be narrowed to a single project with the project filter, and each row carries a chip naming its project.
Listing Notifications
Section titled “Listing Notifications”GET /api/notificationsFilter by tab
Section titled “Filter by tab”| Tab | What it shows |
|---|---|
all |
Every non-dismissed notification |
important |
High-importance notifications only |
other |
Normal-importance notifications |
snoozed |
Notifications snoozed until a future time |
cleared |
Previously dismissed notifications |
GET /api/notifications?tab=importantNotification Counts
Section titled “Notification Counts”Get the unread badge counts for the UI:
GET /api/notifications/countsGET /api/notifications/statsResponse:
{ "unread": 3, "important": 1, "pendingQuestions": 1}Marking as Read
Section titled “Marking as Read”Mark a single notification as read:
PATCH /api/notifications/{id}/readMark all as read:
POST /api/notifications/mark-all-readDismissing a Notification
Section titled “Dismissing a Notification”DELETE /api/notifications/{id}/dismissDismissed notifications move to the cleared tab and are hidden from the default view.
Real-Time Updates (SSE)
Section titled “Real-Time Updates (SSE)”Subscribe to a server-sent event stream to receive notifications in real time without polling. There are two streams; which one carries a notification depends on its scope:
GET /api/events/stream/account # account-scope notification eventsGET /api/events/stream?projectId=<id> # that project's eventsAccept: text/event-streamThe account stream carries only account-scope notifications for the calling user. Project-scope notifications — including every document lifecycle event — arrive on that project’s stream, so a client that wants both opens both.
Frames are entity events, not notification events: the SSE event name is
entity.created (or entity.updated) and the payload names the entity. Frames for
documents, graph objects and agent runs travel on the same streams, so filter on
entity:
const source = new EventSource('/api/events/stream?projectId=' + projectId);
source.addEventListener('entity.created', (event) => { const payload = JSON.parse(event.data); if (payload.entity !== 'notification') return; // payload.data.scope === 'project', payload.data.eventKey === 'document.uploaded' refreshUnreadCount();});The stream stays open; reconnect automatically if it drops.