Alarms Module

Overview

Swagger-driven developer documentation for alarms endpoints and contracts.

Key APIs

Method	Path	Summary
GET	`/api/alarms`	Get tenant alarms
GET	`/api/alarms/{alarmId}`	Get single alarm
PATCH	`/api/alarms/{alarmId}/ack`	Acknowledge alarm
GET	`/api/alarms/{alarmId}/events`	Get alarm events
PATCH	`/api/alarms/ack/bulk`	Bulk acknowledge alarms
GET	`/api/alarms/device/{deviceId}`	Get alarms for a device
GET	`/api/alarms/escalation-settings`	Get tenant alarm escalation settings
PATCH	`/api/alarms/escalation-settings`	Update tenant alarm escalation settings

Frontend Usage Flow

Frontend list pages call collection GET endpoints to load tables or summary views.
Detail pages call parameterized GET endpoints to load a single resource before rendering tabs, forms, or detail sections.
Edit flows load existing values, submit to PUT or PATCH endpoints, and then refresh the visible state.

GET `/api/alarms`

Summary: Get tenant alarms

Operation ID: AlarmsController_getTenantAlarms

Tags: Alarms

Security:

bearer

Responses

200

Tenant alarms returned successfully

Content-Type: application/json

Schema:

json

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/AlarmResponseDto"
  }
}

Example:

json

[
  {
    "alarmId": "alarm-123",
    "deviceId": "device-123",
    "deviceType": "mqtt-meter",
    "name": "High Temperature",
    "severity": "CRITICAL",
    "status": "ACTIVE_UNACK",
    "message": "Temperature exceeded threshold",
    "createdAt": "2026-04-07T10:00:00.000Z",
    "updatedAt": "2026-04-07T10:05:00.000Z",
    "acknowledgedAt": "2026-04-07T10:10:00.000Z"
  }
]

401

Unauthorized

No response body.

Notes / Constraints

Swagger declares security requirements for this operation.

GET `/api/alarms/{alarmId}`

Summary: Get single alarm

Operation ID: AlarmsController_getOne

Tags: Alarms

Security:

bearer

Parameters

Name	In	Required	Type	Description
alarmId	path	yes	string	Alarm identifier

Responses

200

Alarm returned successfully

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "alarmId"
  ],
  "properties": {
    "alarmId": {
      "type": "string"
    },
    "deviceId": {
      "type": "string"
    },
    "deviceType": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "severity": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "createdAt": {
      "type": "string"
    },
    "updatedAt": {
      "type": "string"
    },
    "acknowledgedAt": {
      "type": "string"
    }
  }
}

Example:

json

{
  "alarmId": "alarm-123",
  "deviceId": "device-123",
  "deviceType": "mqtt-meter",
  "name": "High Temperature",
  "severity": "CRITICAL",
  "status": "ACTIVE_UNACK",
  "message": "Temperature exceeded threshold",
  "createdAt": "2026-04-07T10:00:00.000Z",
  "updatedAt": "2026-04-07T10:05:00.000Z",
  "acknowledgedAt": "2026-04-07T10:10:00.000Z"
}

401

Unauthorized

No response body.

Notes / Constraints

This endpoint depends on one or more path parameters.
Swagger declares security requirements for this operation.

PATCH `/api/alarms/{alarmId}/ack`

Summary: Acknowledge alarm

Allowed only for admin or users with acknowledge permission.

Operation ID: AlarmsController_acknowledge

Tags: Alarms

Security:

bearer

Parameters

Name	In	Required	Type	Description
alarmId	path	yes	string	Alarm identifier

Responses

200

Alarm acknowledged successfully

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    }
  }
}

Example:

json

{
  "success": true
}

401

Unauthorized

No response body.

403

You are not allowed to acknowledge alarms

No response body.

Notes / Constraints

This endpoint depends on one or more path parameters.
Swagger declares security requirements for this operation.

GET `/api/alarms/{alarmId}/events`

Summary: Get alarm events

Operation ID: AlarmsController_getEvents

Tags: Alarms

Security:

bearer

Parameters

Name	In	Required	Type	Description
alarmId	path	yes	string	Alarm identifier

Responses

200

Alarm events returned successfully

Content-Type: application/json

Schema:

json

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/AlarmEventResponseDto"
  }
}

Example:

json

[
  {
    "eventId": "event-123",
    "alarmId": "alarm-123",
    "eventType": "ACK",
    "message": "Alarm acknowledged by admin",
    "createdAt": "2026-04-07T10:12:00.000Z"
  }
]

401

Unauthorized

No response body.

Notes / Constraints

This endpoint depends on one or more path parameters.
Swagger declares security requirements for this operation.

PATCH `/api/alarms/ack/bulk`

Summary: Bulk acknowledge alarms

Allowed only for admin or users with acknowledge permission.

Operation ID: AlarmsController_acknowledgeBulk

Tags: Alarms

Security:

bearer

Request

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "alarmIds"
  ],
  "properties": {
    "alarmIds": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

Example:

json

{
  "alarmIds": [
    "alarm-123",
    "alarm-456"
  ]
}

Responses

200

Bulk acknowledge completed

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    }
  }
}

Example:

json

{
  "success": true
}

400

Invalid alarmIds payload

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "statusCode",
    "error"
  ],
  "properties": {
    "statusCode": {
      "type": "number"
    },
    "error": {
      "type": "string"
    },
    "message": {
      "type": "object"
    }
  }
}

Example:

json

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid time range"
}

401

Unauthorized

No response body.

403

You are not allowed to acknowledge alarms

No response body.

Notes / Constraints

Supported request content types: application/json.
Swagger declares security requirements for this operation.

GET `/api/alarms/device/{deviceId}`

Summary: Get alarms for a device

Operation ID: AlarmsController_getByDevice

Tags: Alarms

Security:

bearer

Parameters

Name	In	Required	Type	Description
deviceId	path	yes	string	Device identifier

Responses

200

Device alarms returned successfully

Content-Type: application/json

Schema:

json

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/AlarmResponseDto"
  }
}

Example:

json

[
  {
    "alarmId": "alarm-123",
    "deviceId": "device-123",
    "deviceType": "mqtt-meter",
    "name": "High Temperature",
    "severity": "CRITICAL",
    "status": "ACTIVE_UNACK",
    "message": "Temperature exceeded threshold",
    "createdAt": "2026-04-07T10:00:00.000Z",
    "updatedAt": "2026-04-07T10:05:00.000Z",
    "acknowledgedAt": "2026-04-07T10:10:00.000Z"
  }
]

401

Unauthorized

No response body.

Notes / Constraints

This endpoint depends on one or more path parameters.
Swagger declares security requirements for this operation.

GET `/api/alarms/escalation-settings`

Summary: Get tenant alarm escalation settings

Admin/owner only.

Operation ID: AlarmsController_getEscalationSettings

Tags: Alarms

Security:

bearer

Responses

200

Escalation settings returned successfully

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "level1To2Minutes",
    "level2To3Minutes",
    "stopOnAck",
    "stopOnClear"
  ],
  "properties": {
    "level1To2Minutes": {
      "type": "number"
    },
    "level2To3Minutes": {
      "type": "number"
    },
    "stopOnAck": {
      "type": "boolean"
    },
    "stopOnClear": {
      "type": "boolean"
    }
  }
}

Example:

json

{
  "level1To2Minutes": 10,
  "level2To3Minutes": 20,
  "stopOnAck": true,
  "stopOnClear": true
}

401

Unauthorized

No response body.

403

Only tenant admin or owner can manage escalation settings

No response body.

Notes / Constraints

Swagger declares security requirements for this operation.

PATCH `/api/alarms/escalation-settings`

Summary: Update tenant alarm escalation settings

Admin/owner only.

Operation ID: AlarmsController_updateEscalationSettings

Tags: Alarms

Security:

bearer

Request

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "level1To2Minutes",
    "level2To3Minutes",
    "stopOnAck",
    "stopOnClear"
  ],
  "properties": {
    "level1To2Minutes": {
      "type": "number"
    },
    "level2To3Minutes": {
      "type": "number"
    },
    "stopOnAck": {
      "type": "boolean"
    },
    "stopOnClear": {
      "type": "boolean"
    }
  }
}

Example:

json

{
  "level1To2Minutes": 10,
  "level2To3Minutes": 20,
  "stopOnAck": true,
  "stopOnClear": true
}

Responses

200

Escalation settings updated successfully

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "level1To2Minutes",
    "level2To3Minutes",
    "stopOnAck",
    "stopOnClear"
  ],
  "properties": {
    "level1To2Minutes": {
      "type": "number"
    },
    "level2To3Minutes": {
      "type": "number"
    },
    "stopOnAck": {
      "type": "boolean"
    },
    "stopOnClear": {
      "type": "boolean"
    }
  }
}

Example:

json

{
  "level1To2Minutes": 10,
  "level2To3Minutes": 20,
  "stopOnAck": true,
  "stopOnClear": true
}

401

Unauthorized

No response body.

403

Only tenant admin or owner can manage escalation settings

No response body.

Notes / Constraints

Supported request content types: application/json.
Swagger declares security requirements for this operation.

Module Notes / Constraints

Generated from OpenAPI version metadata: 1.0.
8 operation(s) in this module declare explicit Swagger security requirements.
HTTP methods present in this module: GET, PATCH.
This file is generated from Swagger/OpenAPI and should be regenerated when controller, DTO, or Swagger decorator changes affect the spec.

Alarms Module ​

Overview ​

Key APIs ​

Frontend Usage Flow ​

GET /api/alarms ​

Responses ​

200 ​

401 ​

Notes / Constraints ​

GET /api/alarms/{alarmId} ​

Parameters ​

Responses ​

200 ​

401 ​

Notes / Constraints ​

PATCH /api/alarms/{alarmId}/ack ​

Parameters ​

Responses ​

200 ​

401 ​

403 ​

Notes / Constraints ​

GET /api/alarms/{alarmId}/events ​

Parameters ​

Responses ​

200 ​

401 ​

Notes / Constraints ​

PATCH /api/alarms/ack/bulk ​

Request ​

Responses ​

200 ​

400 ​

401 ​

403 ​

Notes / Constraints ​

GET /api/alarms/device/{deviceId} ​

Parameters ​

Responses ​

200 ​

401 ​

Notes / Constraints ​

GET /api/alarms/escalation-settings ​

Responses ​

200 ​

401 ​

403 ​

Notes / Constraints ​

PATCH /api/alarms/escalation-settings ​

Request ​

Responses ​

200 ​

401 ​

403 ​

Notes / Constraints ​

Module Notes / Constraints ​

Alarms Module

Overview

Key APIs

Frontend Usage Flow

GET `/api/alarms`

Responses

200

401

Notes / Constraints

GET `/api/alarms/{alarmId}`

Parameters

Responses

200

401

Notes / Constraints

PATCH `/api/alarms/{alarmId}/ack`

Parameters

Responses

200

401

403

Notes / Constraints

GET `/api/alarms/{alarmId}/events`

Parameters

Responses

200

401

Notes / Constraints

PATCH `/api/alarms/ack/bulk`

Request

Responses

200

400

401

403

Notes / Constraints

GET `/api/alarms/device/{deviceId}`

Parameters

Responses

200

401

Notes / Constraints

GET `/api/alarms/escalation-settings`

Responses

200

401

403

Notes / Constraints

PATCH `/api/alarms/escalation-settings`

Request

Responses

200

401

403

Notes / Constraints

Module Notes / Constraints