Alerts API - Invenicum

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

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

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

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

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

Created: Alert is generated (manual or automatic)
Delivered: Notification sent to user (via push, email, in-app)
Read: User acknowledges the alert
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();
});

Authentication

Inventory

Management

Data & Reports

Extensions

​Overview

​Endpoints

​Get Alerts

​Response

​Example Request

​Example Response

​Create Alert

​Request Body

​Response

​Example Request - Simple Alert

​Example Request - Scheduled Event

​Example Response

​Update Alert

​Path Parameters

​Request Body

​Example Request

​Delete Alert

​Path Parameters

​Example Request

​Error Responses

​Mark Alert as Read

​Path Parameters

​Example Request

​Response

​Alert Types

​Info

​Warning

​Critical

​Business Logic Notes

​Alert vs Event Distinction

​Notification Scheduling

​Read Status Management

​Date Format

​Automatic Alert Generation

​Alert Lifecycle

​Performance Considerations

​UI Integration

Build docs developers (and LLMs) love

Overview

Endpoints

Get Alerts

Response

Example Request

Example Response

Create Alert

Request Body

Response

Example Request - Simple Alert

Example Request - Scheduled Event

Example Response

Update Alert

Path Parameters

Request Body

Example Request

Delete Alert

Path Parameters

Example Request

Error Responses

Mark Alert as Read

Path Parameters

Example Request

Response

Alert Types

Info

Warning

Critical

Business Logic Notes

Alert vs Event Distinction

Notification Scheduling

Read Status Management

Date Format

Automatic Alert Generation

Alert Lifecycle

Performance Considerations

UI Integration