> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/lopiv2/invenicum/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```http theme={null}
GET /alerts
```

#### Response

<ResponseField name="data" type="Alert[]">
  Array of alert objects

  <Expandable title="Alert Object">
    <ResponseField name="id" type="integer">
      Unique identifier for the alert
    </ResponseField>

    <ResponseField name="title" type="string">
      Title/subject of the alert
    </ResponseField>

    <ResponseField name="message" type="string">
      Detailed message content
    </ResponseField>

    <ResponseField name="type" type="string">
      Alert severity level: 'info', 'warning', or 'critical'
    </ResponseField>

    <ResponseField name="createdAt" type="string" format="datetime">
      Timestamp when the alert was created (ISO 8601)
    </ResponseField>

    <ResponseField name="isRead" type="boolean">
      Whether the alert has been read by the user (default: false)
    </ResponseField>

    <ResponseField name="isEvent" type="boolean">
      Whether this is a calendar event (default: false)
    </ResponseField>

    <ResponseField name="scheduledAt" type="string" format="datetime" optional>
      When the event is scheduled to occur (for calendar events)
    </ResponseField>

    <ResponseField name="notifyAt" type="string" format="datetime" optional>
      When to trigger the notification (for scheduled notifications)
    </ResponseField>
  </Expandable>
</ResponseField>

#### Example Request

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

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

#### Example Response

```json theme={null}
{
  "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.

```http theme={null}
POST /alerts
```

#### Request Body

<ParamField body="title" type="string" required>
  Title/subject of the alert
</ParamField>

<ParamField body="message" type="string" required>
  Detailed message content
</ParamField>

<ParamField body="type" type="string" default="info">
  Alert severity: 'info', 'warning', or 'critical'
</ParamField>

<ParamField body="isRead" type="boolean" default="false">
  Initial read status (typically false for new alerts)
</ParamField>

<ParamField body="isEvent" type="boolean" default="false">
  Whether this is a calendar event
</ParamField>

<ParamField body="scheduledAt" type="string" format="datetime" optional>
  When the event is scheduled (ISO 8601 format)
</ParamField>

<ParamField body="notifyAt" type="string" format="datetime" optional>
  When to send the notification (ISO 8601 format)
</ParamField>

#### Response

<ResponseField name="data" type="Alert">
  The newly created alert object
</ResponseField>

#### Example Request - Simple Alert

```javascript theme={null}
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

```javascript theme={null}
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

```json theme={null}
{
  "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.

```http theme={null}
PUT /alerts/{id}
```

#### Path Parameters

<ParamField path="id" type="integer" required>
  The ID of the alert to update
</ParamField>

#### Request Body

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

<ParamField body="title" type="string" optional>
  Updated title
</ParamField>

<ParamField body="message" type="string" optional>
  Updated message
</ParamField>

<ParamField body="type" type="string" optional>
  Updated severity level
</ParamField>

<ParamField body="isRead" type="boolean" optional>
  Updated read status
</ParamField>

<ParamField body="isEvent" type="boolean" optional>
  Updated event flag
</ParamField>

<ParamField body="scheduledAt" type="string" optional>
  Updated scheduled time
</ParamField>

<ParamField body="notifyAt" type="string" optional>
  Updated notification time
</ParamField>

#### Example Request

```javascript theme={null}
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.

```http theme={null}
DELETE /alerts/{id}
```

#### Path Parameters

<ParamField path="id" type="integer" required>
  The ID of the alert to delete
</ParamField>

#### Example Request

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

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

#### Error Responses

<ResponseField name="200" type="success">
  Alert deleted successfully
</ResponseField>

<ResponseField name="404" type="error">
  Alert not found
</ResponseField>

<ResponseField name="401" type="error">
  Unauthorized - Authentication required
</ResponseField>

***

### Mark Alert as Read

Marks a specific alert as read.

```http theme={null}
PATCH /alerts/{id}/read
```

#### Path Parameters

<ParamField path="id" type="integer" required>
  The ID of the alert to mark as read
</ParamField>

#### Example Request

```javascript theme={null}
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

```javascript theme={null}
// 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();
});
```