Notifications API

The Notifications API manages system notifications for users, including processing updates, alerts, reminders, and system messages. Notifications are automatically created by the system for various events.

Notification Model

id: Unique notification identifier (string)
type: Notification type (string: "SYSTEM" | "REMINDER" | "ALERT" | "MESSAGE")
content: Notification message content (string)
read: Read status (boolean)
userId: Target user ID (string)
createdAt: ISO datetime when created (string)
updatedAt: ISO datetime when last updated (string)

Notification Types

SYSTEM: General system updates, processing completion messages
REMINDER: User reminders and scheduled notifications
ALERT: Important alerts and error notifications
MESSAGE: Direct messages and communication

Endpoints

All notification endpoints require authentication and are scoped to the authenticated user.

Get User Notifications

Retrieve notifications for the authenticated user with optional filtering and limiting.

GET /api/notifications

# Limit number of notifications
GET /api/notifications?limit=20

# Exclude read notifications
GET /api/notifications?includeRead=false

# Both parameters
GET /api/notifications?limit=10&includeRead=false

Query Parameters

limit: Number of notifications to return (optional, default: 50)
includeRead: Include read notifications (optional, default: true, accepts "true" or "false" as string)

Response (200)

{
  "success": true,
  "data": {
    "notifications": [
      {
        "id": "notification_abc123",
        "type": "SYSTEM",
        "content": "✅ Your lecture \"Biology Lecture 5\" has been successfully processed and is ready to view!",
        "read": false,
        "userId": "user_123",
        "createdAt": "2024-01-15T10:05:00.000Z",
        "updatedAt": "2024-01-15T10:05:00.000Z"
      },
      {
        "id": "notification_def456",
        "type": "ALERT",
        "content": "❌ Failed to process lecture \"Audio Recording\". Error: File format not supported. Please try again or contact support.",
        "read": true,
        "userId": "user_123",
        "createdAt": "2024-01-14T15:30:00.000Z",
        "updatedAt": "2024-01-14T16:00:00.000Z"
      },
      {
        "id": "notification_ghi789",
        "type": "SYSTEM",
        "content": "📋 Your syllabus \"Biology 101 Syllabus\" has been successfully processed! I've also created 15 calendar events from your syllabus!",
        "read": false,
        "userId": "user_123",
        "createdAt": "2024-01-13T09:15:00.000Z",
        "updatedAt": "2024-01-13T09:15:00.000Z"
      }
    ],
    "unreadCount": 2,
    "total": 3
  },
  "message": "Notifications retrieved successfully"
}

Errors:

400: Invalid query parameters
401: Authentication required
500: Failed to fetch notifications

Get Unread Count

Retrieve the count of unread notifications for the authenticated user.

GET /api/notifications/unread-count

Response (200)

{
  "success": true,
  "data": {
    "unreadCount": 5
  },
  "message": "Unread count retrieved successfully"
}

Errors:

401: Authentication required
500: Failed to get unread count

Mark Notification as Read

Mark a specific notification as read by its ID.

PATCH /api/notifications/{id}/read

Path Parameters

id: Notification ID (required)

Response (200)

{
  "success": true,
  "message": "Notification marked as read"
}

Errors:

400: Invalid notification ID
401: Authentication required
404: Notification not found or access denied
500: Failed to mark notification as read

Mark All Notifications as Read

Mark all notifications as read for the authenticated user.

PATCH /api/notifications/read-all

Response (200)

{
  "success": true,
  "data": {
    "markedCount": 8
  },
  "message": "Marked 8 notifications as read"
}

Errors:

401: Authentication required
500: Failed to mark all notifications as read

Automatic Notification Creation

The system automatically creates notifications for various events:

Lecture Processing

Processing Started: When YouTube or audio import begins
Processing Complete: When lecture transcription and processing succeeds
Processing Failed: When lecture processing encounters errors

Document Processing

Processing Started: When document upload begins processing
Processing Complete: When document text extraction and indexing succeeds
Processing Failed: When document processing encounters errors

Syllabus Processing

Processing Complete: When syllabus processing succeeds with calendar event count
Processing Failed: When syllabus processing encounters errors
Calendar Events Created: When calendar events are automatically created from syllabus

System Events

General Updates: System maintenance, feature announcements
Reminders: User-configured reminders and alerts

Notification Content Examples

Success Notifications

✅ Your lecture "Biology Lecture 5" has been successfully processed and is ready to view!
📄 Your document "Chapter 1 Notes" has been successfully processed and indexed for search!
📋 Your syllabus "Biology 101 Syllabus" has been successfully processed! I've also created 15 calendar events from your syllabus!
📅 Created 12 calendar events for "Biology 101" from your syllabus! Check your calendar to see exam dates, assignment deadlines, and class schedule.

Processing Notifications

🔄 Started processing your lecture "Biology Lecture 5". You'll be notified when it's ready!
🔄 Started processing your document "Chapter 1 Notes". You'll be notified when it's ready!

Error Notifications

❌ Failed to process lecture "Audio Recording". Error: File format not supported. Please try again or contact support.
❌ Failed to process document "Lecture Slides". Error: File corrupted. Please try uploading again.
❌ Failed to process syllabus "Course Syllabus". Error: Unable to extract calendar events. Please try uploading again.

Data Management

Notification Lifecycle

Creation: Automatically created by system events
Reading: Marked as read when user interacts with notification
Cleanup: Read notifications older than 30 days may be automatically cleaned up

Performance Considerations

Notifications are ordered by creation date (newest first)
Limit parameter prevents excessive data transfer
Unread count is optimized with database indexing
includeRead=false filter reduces response size for unread-only views

Authentication

All notification endpoints require session-based authentication. Users can only access their own notifications. The system ensures notification isolation between users.

Notifications are created in response to:

Import Jobs: YouTube and audio file processing completion/failure
Document Processing: Document upload and text extraction completion/failure
Calendar Integration: Syllabus parsing and event creation
System Events: Maintenance, updates, and user-triggered actions

Integration Patterns

Frontend Integration

// Get unread count for badge display
const unreadResponse = await fetch('/api/notifications/unread-count');
const { data: { unreadCount } } = await unreadResponse.json();

// Get recent unread notifications
const notificationsResponse = await fetch('/api/notifications?limit=10&includeRead=false');
const { data: { notifications } } = await notificationsResponse.json();

// Mark notification as read when user clicks
await fetch(`/api/notifications/${notificationId}/read`, { method: 'PATCH' });

// Mark all as read when user dismisses all
await fetch('/api/notifications/read-all', { method: 'PATCH' });

Real-time Updates

While the API doesn't include real-time capabilities, notifications are typically:

Polled periodically for unread count updates
Fetched on page load for notification dropdown/panel
Refreshed after user actions that might generate notifications

Notifications API

On this page