Alert Catalog - Invernaderos API

Overview

The Alert Catalog defines:

Alert Types: Categories of alerts (THRESHOLD_EXCEEDED, SENSOR_OFFLINE, ACTUATOR_FAILURE, SYSTEM_ERROR)
Alert Severities: Priority levels (INFO, WARNING, ERROR, CRITICAL) with action requirements

This catalog enables standardized alert classification and automated alert handling across the Invernaderos system.

Alert Types

Get All Alert Types

curl -X GET "https://api.invernaderos.com/api/v1/catalog/alert-types" \
  -H "Authorization: Bearer YOUR_TOKEN"

Retrieves all available alert types.

Response

data

array

Array of alert type objects

Show AlertTypeResponse

short

required

Unique identifier

name

string

required

Alert type name (e.g., “THRESHOLD_EXCEEDED”, “SENSOR_OFFLINE”)

description

string

Description of the alert type

[
  {
    "id": 1,
    "name": "THRESHOLD_EXCEEDED",
    "description": "Sensor value exceeded configured threshold"
  },
  {
    "id": 2,
    "name": "SENSOR_OFFLINE",
    "description": "Sensor has not reported data in expected timeframe"
  },
  {
    "id": 3,
    "name": "ACTUATOR_FAILURE",
    "description": "Actuator failed to execute command or reported error state"
  },
  {
    "id": 4,
    "name": "SYSTEM_ERROR",
    "description": "System-level error occurred (database, network, etc.)"
  }
]

System Alert TypesCommon alert types with predefined IDs:

ID 1 = THRESHOLD_EXCEEDED (sensor value out of range)
ID 2 = SENSOR_OFFLINE (sensor not responding)
ID 3 = ACTUATOR_FAILURE (actuator malfunction)
ID 4 = SYSTEM_ERROR (system-level issues)

Get Alert Type by ID

curl -X GET "https://api.invernaderos.com/api/v1/catalog/alert-types/1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Path Parameters

short

required

Alert type ID

Response

{
  "id": 1,
  "name": "THRESHOLD_EXCEEDED",
  "description": "Sensor value exceeded configured threshold"
}

Create Alert Type

curl -X POST "https://api.invernaderos.com/api/v1/catalog/alert-types" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MAINTENANCE_REQUIRED",
    "description": "Scheduled maintenance is due for greenhouse equipment"
  }'

Request Body

name

string

required

Alert type name (max 30 characters, must be unique)

description

string

Description of the alert type

Response

{
  "id": 5,
  "name": "MAINTENANCE_REQUIRED",
  "description": "Scheduled maintenance is due for greenhouse equipment"
}

Update Alert Type

curl -X PUT "https://api.invernaderos.com/api/v1/catalog/alert-types/5" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Preventive maintenance is due for greenhouse equipment within 7 days"
  }'

Path Parameters

short

required

Alert type ID to update

Request Body

All fields are optional. Only provided fields will be updated.

name

string

New alert type name (max 30 characters, must be unique)

description

string

New description

Response

Same structure as “Create Alert Type” with updated values.

Delete Alert Type

curl -X DELETE "https://api.invernaderos.com/api/v1/catalog/alert-types/5" \
  -H "Authorization: Bearer YOUR_TOKEN"

Path Parameters

short

required

Alert type ID to delete

Response

Alert type deleted successfully (no body)

Deletion ConstraintsCannot delete alert types that have associated alert records. You must:

Delete or archive all alerts using this type first, OR
Consider if this type should remain for historical data

Alert Severities

Get All Alert Severities

curl -X GET "https://api.invernaderos.com/api/v1/catalog/alert-severities" \
  -H "Authorization: Bearer YOUR_TOKEN"

Retrieves all severity levels ordered by level (1=lowest, 4=highest).

Response

data

array

Array of alert severity objects

Show AlertSeverityResponse

short

required

Unique identifier

name

string

required

Severity name (e.g., “INFO”, “WARNING”, “ERROR”, “CRITICAL”)

level

short

required

Numeric level for sorting (1=lowest, higher=more severe)

description

string

Description of the severity level

color

string

Hex color code for UI visualization (e.g., “#0066FF”)

requiresAction

boolean

required

Whether immediate action is required

notificationDelayMinutes

integer

required

Minutes to wait before sending notification (0=immediate)

[
  {
    "id": 1,
    "name": "INFO",
    "level": 1,
    "description": "Informational message, no action required",
    "color": "#0066FF",
    "requiresAction": false,
    "notificationDelayMinutes": 60
  },
  {
    "id": 2,
    "name": "WARNING",
    "level": 2,
    "description": "Potential issue, should be reviewed",
    "color": "#FFA500",
    "requiresAction": false,
    "notificationDelayMinutes": 15
  },
  {
    "id": 3,
    "name": "ERROR",
    "level": 3,
    "description": "Error occurred, action required soon",
    "color": "#FF6600",
    "requiresAction": true,
    "notificationDelayMinutes": 5
  },
  {
    "id": 4,
    "name": "CRITICAL",
    "level": 4,
    "description": "Critical issue, immediate action required",
    "color": "#FF0000",
    "requiresAction": true,
    "notificationDelayMinutes": 0
  }
]

System Severity LevelsStandard severity levels with predefined IDs:

ID 1 = INFO (level 1, blue, no action required)
ID 2 = WARNING (level 2, orange, review recommended)
ID 3 = ERROR (level 3, dark orange, action required)
ID 4 = CRITICAL (level 4, red, immediate action required)

Get Critical Severities

curl -X GET "https://api.invernaderos.com/api/v1/catalog/alert-severities/critical" \
  -H "Authorization: Bearer YOUR_TOKEN"

Retrieves only severities that require immediate action (requiresAction = true).

Response

[
  {
    "id": 3,
    "name": "ERROR",
    "level": 3,
    "description": "Error occurred, action required soon",
    "color": "#FF6600",
    "requiresAction": true,
    "notificationDelayMinutes": 5
  },
  {
    "id": 4,
    "name": "CRITICAL",
    "level": 4,
    "description": "Critical issue, immediate action required",
    "color": "#FF0000",
    "requiresAction": true,
    "notificationDelayMinutes": 0
  }
]

Use Case: Filter alerts that require user attention in dashboards.

Get Alert Severity by ID

curl -X GET "https://api.invernaderos.com/api/v1/catalog/alert-severities/4" \
  -H "Authorization: Bearer YOUR_TOKEN"

Path Parameters

short

required

Alert severity ID

Response

{
  "id": 4,
  "name": "CRITICAL",
  "level": 4,
  "description": "Critical issue, immediate action required",
  "color": "#FF0000",
  "requiresAction": true,
  "notificationDelayMinutes": 0
}

Create Alert Severity

curl -X POST "https://api.invernaderos.com/api/v1/catalog/alert-severities" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "URGENT",
    "level": 5,
    "description": "Extremely urgent issue requiring immediate escalation",
    "color": "#8B0000",
    "requiresAction": true,
    "notificationDelayMinutes": 0
  }'

Request Body

name

string

required

Severity name (max 20 characters, must be unique)

level

short

required

Numeric level for sorting (1=lowest, higher=more severe, must be positive)

description

string

Description of the severity level

color

string

Hex color code (format: #RRGGBB, e.g., “#FF0000”)

requiresAction

boolean

default:"false"

Whether immediate action is required

notificationDelayMinutes

integer

default:"0"

Minutes to wait before sending notification (minimum 0)

Response

{
  "id": 5,
  "name": "URGENT",
  "level": 5,
  "description": "Extremely urgent issue requiring immediate escalation",
  "color": "#8B0000",
  "requiresAction": true,
  "notificationDelayMinutes": 0
}

Update Alert Severity

curl -X PUT "https://api.invernaderos.com/api/v1/catalog/alert-severities/5" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notificationDelayMinutes": 0,
    "description": "Extremely urgent - escalate to manager immediately"
  }'

Path Parameters

short

required

Alert severity ID to update

Request Body

All fields are optional. Only provided fields will be updated.

name

string

New severity name (max 20 characters, must be unique)

level

short

New numeric level (must be positive)

description

string

New description

color

string

New hex color code

requiresAction

boolean

New action requirement status

notificationDelayMinutes

integer

New notification delay (minimum 0)

Response

Same structure as “Create Alert Severity” with updated values.

Delete Alert Severity

curl -X DELETE "https://api.invernaderos.com/api/v1/catalog/alert-severities/5" \
  -H "Authorization: Bearer YOUR_TOKEN"

Path Parameters

short

required

Alert severity ID to delete

Response

Alert severity deleted successfully (no body)

Alert Configuration Workflow

Define Alert Types

Create custom alert types specific to your greenhouse operations:

POST /api/v1/catalog/alert-types
{
  "name": "NUTRIENT_IMBALANCE",
  "description": "Nutrient levels are outside optimal range"
}

Configure Severities

Set up severity levels with appropriate notification delays:

POST /api/v1/catalog/alert-severities
{
  "name": "LOW",
  "level": 1,
  "color": "#ADD8E6",
  "requiresAction": false,
  "notificationDelayMinutes": 120  // Wait 2 hours
}

Create Alerts with Types and Severities

When creating alerts, reference catalog IDs:

POST /api/v1/alerts
{
  "greenhouseId": "550e8400-e29b-41d4-a716-446655440000",
  "alertTypeId": 1,      // THRESHOLD_EXCEEDED
  "severityId": 4,       // CRITICAL
  "message": "Temperature exceeded 35°C",
  "sensorId": "TEMP_01"
}

Filter Alerts by Severity

Query alerts requiring immediate action:

GET /api/v1/alerts?requiresAction=true&isResolved=false

Returns only ERROR and CRITICAL unresolved alerts.

Notification Delay Explained

How Notification Delays Work

Purpose: Prevent alert fatigue by delaying notifications for less critical issues.Behavior:

notificationDelayMinutes = 0: Notify immediately
notificationDelayMinutes > 0: Wait specified minutes before sending notification
If alert is resolved during delay period, no notification is sent

Use Cases:

Severity	Delay	Reason
INFO	60 min	Batch informational alerts hourly
WARNING	15 min	Give system time to self-correct
ERROR	5 min	Brief delay to avoid transient errors
CRITICAL	0 min	Immediate notification required

Example Scenario:

00 AM - Temperature exceeds threshold (WARNING, delay 15 min)
05 AM - Temperature returns to normal (alert auto-resolved)
15 AM - No notification sent (alert was resolved during delay)

Implementation:

// Check if alert should trigger notification
const shouldNotify = (alert, severity) => {
  const alertAge = Date.now() - new Date(alert.createdAt).getTime();
  const delayMs = severity.notificationDelayMinutes * 60 * 1000;
  
  return !alert.isResolved && alertAge >= delayMs;
};

Integration Examples

// Get critical unresolved alerts for dashboard
const loadCriticalAlerts = async () => {
  // Get critical severities
  const severities = await fetch(
    'https://api.invernaderos.com/api/v1/catalog/alert-severities/critical',
    { headers: { 'Authorization': `Bearer ${token}` } }
  ).then(res => res.json());
  
  const criticalSeverityIds = severities.map(s => s.id);
  
  // Get unresolved alerts with critical severities
  const alerts = await fetch(
    `https://api.invernaderos.com/api/v1/alerts?isResolved=false&severityIds=${criticalSeverityIds.join(',')}`,
    { headers: { 'Authorization': `Bearer ${token}` } }
  ).then(res => res.json());
  
  return alerts;
};

// Display alerts with severity colors
const displayAlerts = async (alerts) => {
  const severities = await fetch(
    'https://api.invernaderos.com/api/v1/catalog/alert-severities',
    { headers: { 'Authorization': `Bearer ${token}` } }
  ).then(res => res.json());
  
  const severityMap = Object.fromEntries(
    severities.map(s => [s.id, s])
  );
  
  alerts.forEach(alert => {
    const severity = severityMap[alert.severityId];
    console.log(
      `[${severity.name}] ${alert.message}`,
      `Color: ${severity.color}`,
      `Requires Action: ${severity.requiresAction}`
    );
  });
};

Error Codes

Status Code	Description	Resolution
200 OK	Request successful	-
201 Created	Resource created successfully	-
204 No Content	Resource deleted successfully	-
400 Bad Request	Invalid input (duplicate name, invalid color, invalid level)	Check error message for details
404 Not Found	Resource not found with specified ID	Verify the ID exists
409 Conflict	Cannot delete resource due to dependencies (alerts using type/severity)	Delete dependent alerts first

Best Practices

Alert Type Naming

Use descriptive, action-oriented names:Good:

THRESHOLD_EXCEEDED
SENSOR_OFFLINE
NUTRIENT_IMBALANCE
MAINTENANCE_REQUIRED

Bad:

ALERT_1
PROBLEM
ISSUE
ERROR_TYPE

Naming Convention:

Use UPPER_SNAKE_CASE
Start with subject (SENSOR, ACTUATOR, SYSTEM)
End with action/state (OFFLINE, FAILURE, EXCEEDED)

Severity Level Design

Standard 4-Level System (Recommended):

INFO (level 1): Informational, no action needed
WARNING (level 2): Potential issue, review recommended
ERROR (level 3): Issue occurred, action needed soon
CRITICAL (level 4): Urgent issue, immediate action required

Extended 5-Level System (For complex operations):

INFO
LOW
MEDIUM
HIGH
CRITICAL

Key Principles:

Keep levels consistent across system
Use requiresAction=true only for ERROR and above
Set appropriate notification delays (avoid alert fatigue)
Choose colors that are colorblind-friendly

Notification Delay Strategy

Recommended Delays by Severity:

Severity	Delay	Rationale
INFO	60-120 min	Batch non-critical updates
WARNING	15-30 min	Allow time for auto-recovery
ERROR	5 min	Brief delay to filter transients
CRITICAL	0 min	Immediate notification

Considerations:

Longer delays reduce notification fatigue
Too long delays may miss critical issues
Allow auto-resolution during delay period
Document delay strategy in alert type description

Color Accessibility

Use colorblind-friendly colors:

Severity	Color	Hex	Accessible
INFO	Blue	`#0066FF`	✅ Good contrast
WARNING	Orange	`#FFA500`	✅ Distinct from red
ERROR	Dark Orange	`#FF6600`	✅ Between warning and critical
CRITICAL	Red	`#FF0000`	✅ Universal danger signal

Avoid:

Pure green/red combinations (deuteranopia)
Low contrast colors (readability)
Similar shades for different severities

Authentication

Tenant Management

Sensor Data

MQTT

Catalogs

Additional Endpoints

​Overview

​Alert Types

​Get All Alert Types

​Response

​Get Alert Type by ID

​Path Parameters

​Response

​Create Alert Type

​Request Body

​Response

​Update Alert Type

​Path Parameters

​Request Body

​Response

​Delete Alert Type

​Path Parameters

​Response

​Alert Severities

​Get All Alert Severities

​Response

​Get Critical Severities

​Response

​Get Alert Severity by ID

​Path Parameters

​Response

​Create Alert Severity

​Request Body

​Response

​Update Alert Severity

​Path Parameters

​Request Body

​Response

​Delete Alert Severity

​Path Parameters

​Response

​Alert Configuration Workflow

​Notification Delay Explained

​Integration Examples

​Error Codes

​Best Practices

Build docs developers (and LLMs) love

Overview

Alert Types

Get All Alert Types

Response

Get Alert Type by ID

Path Parameters

Response

Create Alert Type

Request Body

Response

Update Alert Type

Path Parameters

Request Body

Response

Delete Alert Type

Path Parameters

Response

Alert Severities

Get All Alert Severities

Response

Get Critical Severities

Response

Get Alert Severity by ID

Path Parameters

Response

Create Alert Severity

Request Body

Response

Update Alert Severity

Path Parameters

Request Body

Response

Delete Alert Severity

Path Parameters

Response

Alert Configuration Workflow

Notification Delay Explained

Integration Examples

Error Codes

Best Practices