Skip to main content

​
Overview

Proliferate’s notification system keeps you informed about important events in your projects, such as new errors, team member activity, and integration updates. Notifications appear in the in-app notification center and can be configured per category.

​
Notification Center

Access your notification center from the header of any page. The bell icon shows the count of unread notifications.

​
Viewing Notifications

GET /api/v1/notifications?skip=0&limit=20&unread_only=false
Query Parameters:
​
skip
integer
default:0
Number of notifications to skip (for pagination)
​
limit
integer
default:20
Maximum notifications to return (1-100)
​
category
string
Filter by notification category
​
unread_only
boolean
default:false
Only return unread notifications
​
include_archived
boolean
default:false
Include archived notifications
Response: 
{
  "notifications": [
    {
      "id": 123,
      "user_id": 456,
      "organization_id": 789,
      "category": "error",
      "title": "New error in Production App",
      "summary": "TypeError: Cannot read property 'foo' of undefined",
      "source_type": "issue",
      "source_id": 42,
      "action_url": "/projects/123/issues/42",
      "actor_id": null,
      "actor_type": null,
      "actor_name": null,
      "actor_avatar": null,
      "notification_metadata": {
        "issue_id": 42,
        "project_name": "Production App"
      },
      "read_at": null,
      "archived_at": null,
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "has_more": false
}

​
Unread Count

Get the count of unread notifications: 
GET /api/v1/notifications/unread-count
Response: 
{
  "count": 5
}
This is useful for displaying a badge in your UI.

​
Notification Categories

Notifications are organized into categories:

​
Error Notifications

Category: error Triggered when:
  • A new issue is detected
  • An issue has multiple occurrences in a short time (spike)
  • An issue affects high-value accounts

​
Team Notifications

Category: team Triggered when:
  • A new member joins your organization
  • A member’s role changes
  • An invitation is sent or accepted

​
Integration Notifications

Category: integration Triggered when:
  • A GitHub App installation succeeds or fails
  • A Slack connection is established
  • A Linear issue is created from an error

​
System Notifications

Category: system Triggered when:
  • Platform updates or maintenance
  • Important announcements
  • Security alerts

​
Managing Notifications

​
Mark as Read

Mark a single notification as read: 
PATCH /api/v1/notifications/{notification_id}/read
Response: 
{
  "success": true,
  "read_at": "2025-01-15T11:00:00Z"
}

​
Mark All as Read

Mark all notifications as read: 
POST /api/v1/notifications/mark-all-read
Response: 
{
  "success": true,
  "count": 12
}

​
Archive Notification

Archive a notification to remove it from your default view: 
PATCH /api/v1/notifications/{notification_id}/archive
Archived notifications don’t appear in the notification center unless you explicitly include them with include_archived=true.

​
Notification Preferences

Control which notifications you receive per category.

​
Get Preferences

GET /api/v1/notifications/preferences
Response: 
{
  "preferences": [
    {
      "id": 1,
      "user_id": 456,
      "category": "error",
      "in_app_enabled": true,
      "email_enabled": false,
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-15T10:00:00Z"
    },
    {
      "id": 2,
      "user_id": 456,
      "category": "team",
      "in_app_enabled": true,
      "email_enabled": true,
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    }
  ]
}

​
Update Preferences

Update notification preferences for a specific category: 
curl -X PATCH https://api.proliferate.com/api/v1/notifications/preferences \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "error",
    "in_app_enabled": true,
    "email_enabled": false
  }'
Request Body:
​
category
string
required
The notification category to update (error, team, integration, system)
​
in_app_enabled
boolean
Enable/disable in-app notifications for this category
​
email_enabled
boolean
Enable/disable email notifications for this category
Response: 
{
  "id": 1,
  "user_id": 456,
  "category": "error",
  "in_app_enabled": true,
  "email_enabled": false,
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-15T11:30:00Z"
}

​
Notification Actions

Each notification has an action_url that takes you to the relevant page:
  • Error notifications: Link to the issue detail page
  • Team notifications: Link to the team settings page
  • Integration notifications: Link to the integration settings
Click a notification to navigate to the source and automatically mark it as read.

​
Notification Metadata

The notification_metadata field contains category-specific data:

​
Error Notifications

{
  "issue_id": 42,
  "project_name": "Production App",
  "project_id": 123,
  "event_count": 5,
  "affected_users": 3
}

​
Team Notifications

{
  "member_name": "Jane Doe",
  "member_email": "[email protected]",
  "action": "joined",
  "role": "admin"
}

​
Integration Notifications

{
  "integration_type": "github",
  "status": "connected",
  "repository": "owner/repo"
}

​
Actor Information

For notifications triggered by user actions, the notification includes actor details:
  • actor_id: User ID who triggered the notification
  • actor_type: Type of actor (currently user)
  • actor_name: Display name of the actor
  • actor_avatar: Avatar URL of the actor
Example: “John Doe invited you to join Acme Corp”

​
Best Practices

​
Configure Preferences Early

Set up your notification preferences when joining an organization to avoid notification overload.

​
Use Email Wisely

Enable email notifications only for critical categories (e.g., errors in production). Too many emails can lead to alert fatigue.

​
Check Notifications Regularly

In-app notifications provide a quick overview of recent activity. Check them daily or integrate with your workflow.

​
Archive Read Notifications

Keep your notification center clean by archiving notifications you’ve acted on.

​
Filter by Category

Use the category filter to focus on specific types of notifications (e.g., only errors).

​
Future Enhancements

The notification system will expand to include:
  • Slack notifications: Get notifications in Slack channels
  • Digest emails: Daily or weekly summaries instead of individual emails
  • Custom rules: Create custom notification rules based on error severity, affected accounts, etc.
  • Snooze: Temporarily disable notifications for specific issues
  • @mentions: Notify specific team members in comments