Notifications

Notifications keep you informed about what is happening in your project. Background job completions, mentions from team members, and system events all appear in your notification inbox.

Overview

Every user has a personal notification inbox accessible from the admin dashboard. Notifications are private — you only see notifications meant for you.

Foir automatically creates notifications for background job results, @mentions in notes, note replies, and system events. You can view, filter, and manage notifications from the inbox or programmatically via the CLI and API.

Notification Types

Notification Properties

Each notification includes:

In the Admin

Viewing Notifications

1. Click the notification bell icon in the header
2. See your recent notifications with unread count
3. Click a notification to navigate to the related content
4. Mark individual notifications as read or mark all as read

Filtering

Filter notifications by:

• Unread only — show only notifications you have not read
• Type — filter by notification type (jobs, mentions, system)

Managing Notifications

• Mark as read (single) — click a notification or use the mark-as-read action
• Mark all as read — click Mark all as read to clear your unread count
• Delete — remove notifications you no longer need (deleted notifications cannot be recovered)

Automatic Notifications

Foir creates notifications automatically for:

• Background jobs — When you trigger operations like syncs, search indexing, or file processing, you receive a notification when the job completes or fails. This lets you navigate away and continue working.
• Mentions — When a team member @mentions you in a note, you receive a notification linking directly to the note.
• Note activity — When someone replies to a note you authored or resolves a note you are involved in.

Via the CLI

# List your notifications
foir notifications list
 
# Mark a notification as read
foir notifications read <id>
 
# Mark all notifications as read
foir notifications read-all

Via the API

Real-time Notifications via SSE

The realtime service provides an SSE endpoint for streaming notifications as they happen, without polling. Subscribe to the notifications:{userId} channel:

Endpoint:

GET https://realtime.foir.io/sse/notifications:{userId}?token={customerToken}

Auth is via query parameter: pass a customer JWT as ?token= or an API key as ?apiKey=.

Example (JavaScript):

const source = new EventSource(
  `https://realtime.foir.io/sse/notifications:${userId}?token=${customerToken}`
);
 
source.onmessage = (event) => {
  const { event: eventType, data } = JSON.parse(event.data);
  console.log(`New notification: ${data.title}`);
};
 
source.onerror = () => {
  // EventSource reconnects automatically
};

Each event contains a channel, event type, and data payload with the notification fields.

See Real-time & Subscriptions for the full SSE and WebSocket channel documentation.

Best Practices

• Check notifications regularly — they surface important job results and team activity.
• Use action URLs — click notifications to jump directly to the relevant content.
• Mark as read — keep your inbox clean so new notifications stand out.
• Monitor job notifications — failed jobs may need your attention.
• Use SSE or WebSocket channels for real-time integrations instead of polling the API.