Alerts API

Manage alerts, notifications, and calendar events

Overview

The Alerts API provides notification and calendar event management functionality. It supports creating alerts with different severity levels, scheduling notifications, and managing calendar events. Alerts can be marked as read and support time-based scheduling.

Endpoints

Get Alerts

Retrieves all alerts for the authenticated user.

GET /alerts

Response

data · Alert[]

Array of alert objects

Show Alert Object

id · integer

Unique identifier for the alert

title · string

Title/subject of the alert

message · string

Detailed message content

type · string

Alert severity level: ‘info’, ‘warning’, or ‘critical’

createdAt · string

Timestamp when the alert was created (ISO 8601)

isRead · boolean

Whether the alert has been read by the user (default: false)

isEvent · boolean

Whether this is a calendar event (default: false)

scheduledAt · string

When the event is scheduled to occur (for calendar events)

notifyAt · string

When to trigger the notification (for scheduled notifications)

Example Request

const response = await fetch('/alerts', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
});

const { data } = await response.json();

Example Response

{
  "data": [
    {
      "id": 1,
      "title": "Low Stock Alert",
      "message": "Item 'Laptop Dell XPS 15' is running low on stock (2 remaining)",
      "type": "warning",
      "createdAt": "2026-03-07T10:30:00Z",
      "isRead": false,
      "isEvent": false,
      "scheduledAt": null,
      "notifyAt": null
    },
    {
      "id": 2,
      "title": "Inventory Audit Scheduled",
      "message": "Quarterly inventory audit for Warehouse A",
      "type": "info",
      "createdAt": "2026-03-05T08:00:00Z",
      "isRead": true,
      "isEvent": true,
      "scheduledAt": "2026-03-15T09:00:00Z",
      "notifyAt": "2026-03-14T09:00:00Z"
    }
  ]
}

---

Create Alert

Creates a new alert or notification.

POST /alerts

Request Body

title · string · required

Title/subject of the alert

message · string · required

Detailed message content

type · string · default: "info"

Alert severity: ‘info’, ‘warning’, or ‘critical’

isRead · boolean · default: "false"

Initial read status (typically false for new alerts)

isEvent · boolean · default: "false"

Whether this is a calendar event

scheduledAt · string

When the event is scheduled (ISO 8601 format)

notifyAt · string

When to send the notification (ISO 8601 format)

Response

data · Alert

The newly created alert object

Example Request - Simple Alert

const response = await fetch('/alerts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Low Stock Alert',
    message: 'Item "Laptop Dell XPS 15" is running low on stock',
    type: 'warning'
  })
});

const { data } = await response.json();

Example Request - Scheduled Event

const response = await fetch('/alerts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Quarterly Inventory Audit',
    message: 'Complete inventory count for all warehouses',
    type: 'info',
    isEvent: true,
    scheduledAt: '2026-06-15T09:00:00Z',
    notifyAt: '2026-06-14T09:00:00Z'
  })
});

const { data } = await response.json();

Example Response

{
  "data": {
    "id": 3,
    "title": "Quarterly Inventory Audit",
    "message": "Complete inventory count for all warehouses",
    "type": "info",
    "createdAt": "2026-03-07T14:22:00Z",
    "isRead": false,
    "isEvent": true,
    "scheduledAt": "2026-06-15T09:00:00Z",
    "notifyAt": "2026-06-14T09:00:00Z"
  }
}

---

Update Alert

Updates an existing alert’s details.

PUT /alerts/{id}

Path Parameters

id · integer · required

The ID of the alert to update

Request Body

Accepts the same fields as Create Alert (all optional for updates):

title · string

Updated title

message · string

Updated message

type · string

Updated severity level

isRead · boolean

Updated read status

isEvent · boolean

Updated event flag

scheduledAt · string

Updated scheduled time

notifyAt · string

Updated notification time

Example Request

const response = await fetch('/alerts/3', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Quarterly Inventory Audit - Rescheduled',
    scheduledAt: '2026-06-20T09:00:00Z'
  })
});

---

Delete Alert

Deletes an alert from the system.

DELETE /alerts/{id}

Path Parameters

id · integer · required

The ID of the alert to delete

Example Request

const response = await fetch('/alerts/3', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
});

if (response.ok) {
  console.log('Alert deleted successfully');
}

Error Responses

200 · success

Alert deleted successfully

404 · error

Alert not found

401 · error

Unauthorized - Authentication required

---

Mark Alert as Read

Marks a specific alert as read.

PATCH /alerts/{id}/read

Path Parameters

id · integer · required

The ID of the alert to mark as read

Example Request

const response = await fetch('/alerts/1/read', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
});

if (response.ok) {
  console.log('Alert marked as read');
}

Response

Returns success status (typically 200 OK).

---

Alert Types

The system supports three severity levels:

Info

• General notifications and informational messages
• Calendar events and reminders
• Status updates

Use cases:

• Scheduled maintenance windows
• Upcoming inventory audits
• System announcements

Warning

• Important notifications requiring attention
• Non-critical issues

Use cases:

• Low stock alerts
• Upcoming loan due dates
• Expiring items

Critical

• Urgent notifications requiring immediate action
• System errors or failures

Use cases:

• Out of stock items
• Overdue loans
• Failed system operations
• Security alerts

---

Business Logic Notes

Alert vs Event Distinction

• Alerts (isEvent: false): Notifications about system states or issues
• Events (isEvent: true): Calendar-based items with specific scheduled times
• Events typically have both scheduledAt (event time) and notifyAt (notification time)

Notification Scheduling

• scheduledAt: When the actual event occurs
• notifyAt: When to notify the user about the event
• Example: Event at 9 AM, notification at 8 AM (1 hour advance notice)
• Backend should implement a notification service to process notifyAt times

Read Status Management

• Alerts are created with isRead: false by default
• Use the dedicated /alerts/{id}/read endpoint for marking as read
• This provides better audit trails than direct updates
• Consider implementing bulk “mark all as read” functionality

Date Format

• All timestamps use ISO 8601 format with timezone information
• Always include timezone (typically UTC) in API requests
• Client should convert to local timezone for display

Automatic Alert Generation

Consider implementing automatic alerts for:

• Low stock thresholds (when inventory falls below minimum)
• Overdue loans (daily check for loans past expectedReturnDate)
• Upcoming loan due dates (1-3 days before expectedReturnDate)
• Scheduled maintenance or audit reminders

Alert Lifecycle

1. Created: Alert is generated (manual or automatic)
2. Delivered: Notification sent to user (via push, email, in-app)
3. Read: User acknowledges the alert
4. Archived/Deleted: Alert is removed after a retention period

Performance Considerations

• Implement pagination for alerts list (can grow very large)
• Consider soft deletes for audit purposes
• Archive old read alerts after a retention period (e.g., 30 days)
• Index on isRead and createdAt for efficient querying

UI Integration

// Example: Badge count for unread alerts
const unreadCount = alerts.filter(a => !a.isRead).length;

// Example: Separate critical alerts
const criticalAlerts = alerts.filter(a => a.type === 'critical' && !a.isRead);

// Example: Upcoming events (next 7 days)
const upcomingEvents = alerts.filter(a => {
  if (!a.isEvent || !a.scheduledAt) return false;
  const eventDate = new Date(a.scheduledAt);
  const weekFromNow = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000);
  return eventDate <= weekFromNow && eventDate >= new Date();
});