Skip to main content

​
Overview

The Notifications API allows users to configure email reminders, deadline warnings, weekly digests, and custom reminder schedules for their study plans.

​
Get Notification Settings

curl -X GET "https://your-domain.com/api/notifications/settings" \
  -H "Authorization: Bearer YOUR_TOKEN"
GET /api/notifications/settings Get user’s notification settings. Requires authentication.

​
Response

​
settings
object
Notification settings object

​
Default Settings

If user hasn’t customized settings, returns: 
{
  "settings": {
    "emailReminders": true,
    "reminderTime": "09:00",
    "reminderFrequency": "daily",
    "customDays": [1, 2, 3, 4, 5],
    "deadlineWarnings": true,
    "weeklyDigest": true,
    "customReminders": []
  }
}

​
Update Notification Settings

curl -X PUT "https://your-domain.com/api/notifications/settings" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "emailReminders": true,
    "reminderTime": "08:30",
    "reminderFrequency": "weekdays",
    "deadlineWarnings": true,
    "weeklyDigest": false
  }'
PUT /api/notifications/settings Update notification settings. Requires authentication.

​
Request Body

All fields are optional. Only include fields you want to update.
​
emailReminders
boolean
Enable/disable email reminders
​
reminderTime
string
Default reminder time in HH:MM format (24-hour time)Examples: "09:00", "14:30", "18:45"
​
reminderFrequency
string
Reminder frequency:
  • "daily" - Every day
  • "weekdays" - Monday through Friday only
  • "custom" - Custom days specified in customDays
​
customDays
array
Array of weekday numbers for custom frequency:
  • 0 = Sunday
  • 1 = Monday
  • 2 = Tuesday
  • 3 = Wednesday
  • 4 = Thursday
  • 5 = Friday
  • 6 = Saturday
Example: [1, 3, 5] = Monday, Wednesday, Friday
​
deadlineWarnings
boolean
Enable/disable deadline warning emails (sent when approaching instance end dates)
​
weeklyDigest
boolean
Enable/disable weekly progress digest email
​
customReminders
array
Array of custom reminder objects

​
Response

​
message
string
“Notification settings updated successfully”
​
settings
object
Updated notification settings object

​
Notification Types

​
Email Reminders

Daily/scheduled reminders about active study plan instances:
  • Sent at configured reminderTime
  • Frequency controlled by reminderFrequency and customDays
  • Can be disabled with emailReminders: false
  • Includes upcoming resources and progress summary

​
Deadline Warnings

Warnings when instance end date is approaching:
  • Sent at predefined intervals (e.g., 7 days, 3 days, 1 day before)
  • Controlled by deadlineWarnings setting
  • Includes progress summary and remaining work

​
Weekly Digest

Weekly summary of study progress:
  • Sent once per week
  • Controlled by weeklyDigest setting
  • Includes completion stats, time spent, and upcoming deadlines

​
Custom Reminders

User-defined reminder schedule:
  • Multiple reminders at different times
  • Custom messages for each reminder
  • Specific days for each reminder
  • Stored in customReminders array

​
Share Notifications

In-app notifications when study plans are shared:
  • Not configurable (always sent)
  • Appears in user’s notifications list
  • Includes link to shared study plan

​
Reminder Frequency Examples

​
Daily Reminders

{
  "reminderFrequency": "daily",
  "reminderTime": "09:00"
}
Sends reminder every day at 9:00 AM.

​
Weekday Reminders

{
  "reminderFrequency": "weekdays",
  "reminderTime": "08:30"
}
Sends reminder Monday-Friday at 8:30 AM.

​
Custom Schedule

{
  "reminderFrequency": "custom",
  "customDays": [1, 3, 5],
  "reminderTime": "10:00"
}
Sends reminder Monday, Wednesday, Friday at 10:00 AM.

​
Multiple Custom Reminders

{
  "customReminders": [
    {
      "time": "09:00",
      "message": "Morning study session",
      "days": [1, 2, 3, 4, 5]
    },
    {
      "time": "18:00",
      "message": "Evening review",
      "days": [0, 6]
    }
  ]
}
Morning reminder on weekdays, evening reminder on weekends.

​
Per-Instance Settings

While global settings are managed here, individual instances can override:
  • reminderTime - Custom time for specific instance
  • reminderEnabled - Disable reminders for specific instance
  • customReminders - Instance-specific reminder schedule
Use the Instances API to manage per-instance notification settings.

​
Error Responses

​
400 Bad Request

{
  "error": "No valid fields to update"
}

​
401 Unauthorized

{
  "error": "No token provided"
}

​
404 Not Found

{
  "error": "User not found"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us