# ThingsBoard ThingsBoard Alarms API
# Source: https://demo.thingsboard.io/v3/api-docs (Apache 2.0)
openapi: 3.1.0
info:
title: ThingsBoard Alarms API
description: "ThingsBoard Alarms API \u2014 subset of the ThingsBoard REST API (open-source IoT platform). Covers: Alarm, Alarm Comment."
version: 4.3.0.3DEMO
contact:
name: ThingsBoard team
url: https://thingsboard.io
email: [email protected]
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://demo.thingsboard.io
description: ThingsBoard Live Demo
- url: http://localhost:8080
description: Local ThingsBoard server
tags:
- name: alarm-controller
description: Alarm
- name: alarm-comment-controller
description: Alarm Comment
paths:
/api/alarm:
post:
tags:
- alarm-controller
summary: Create or Update Alarm (saveAlarm)
description: "Creates or Updates the Alarm. When creating alarm, platform generates Alarm Id as [time-based UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address)).\
\ The newly created Alarm id will be present in the response. Specify existing Alarm id to update the alarm. Referencing non-existing Alarm Id will cause 'Not Found' error. \n\nPlatform also deduplicate\
\ the alarms based on the entity id of originator and alarm 'type'. For example, if the user or system component create the alarm with the type 'HighTemperature' for device 'Device A' the new active\
\ alarm is created. If the user tries to create 'HighTemperature' alarm for the same device again, the previous alarm will be updated (the 'end_ts' will be set to current timestamp). If the user\
\ clears the alarm (see 'Clear Alarm(clearAlarm)'), than new alarm with the same type and same device may be created. Remove 'id', 'tenantId' and optionally 'customerId' from the request body example\
\ (below) to create new Alarm entity. \n\nAvailable for users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority."
operationId: saveAlarm
requestBody:
description: A JSON value representing the alarm.
content:
application/json:
schema:
$ref: '#/components/schemas/Alarm'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Alarm'
/api/alarm/{alarmId}/comment:
get:
tags:
- alarm-comment-controller
summary: Get Alarm Comments (getAlarmComments)
description: "Returns a page of alarm comments for specified alarm. You can specify parameters to filter the results. The result is wrapped with PageData object that allows you to iterate over result\
\ set using pagination. See response schema for more details. \n\nAvailable for users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority."
operationId: getAlarmComments
parameters:
- name: alarmId
in: path
description: A string value representing the alarm id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
- name: pageSize
in: query
description: Maximum amount of entities in a one page
required: true
schema:
type: integer
format: int32
- name: page
in: query
description: Sequence number of page starting from 0
required: true
schema:
type: integer
format: int32
- name: sortProperty
in: query
description: Property of entity to sort by
required: false
schema:
type: string
enum:
- createdTime
- id
- name: sortOrder
in: query
description: Sort order. ASC (ASCENDING) or DESC (DESCENDING)
required: false
schema:
type: string
enum:
- ASC
- DESC
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PageDataAlarmCommentInfo'
post:
tags:
- alarm-comment-controller
summary: Create or Update Alarm Comment
description: "Creates or Updates the Alarm Comment. When creating comment, platform generates Alarm Comment Id as [time-based UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address)).\
\ The newly created Alarm Comment id will be present in the response. Specify existing Alarm Comment id to update the alarm. Referencing non-existing Alarm Comment Id will cause 'Not Found' error.\
\ \n\n To create new Alarm comment entity it is enough to specify 'comment' json element with 'text' node, for example: {\"comment\": { \"text\": \"my comment\"}}. \n\n If comment type is not specified\
\ the default value 'OTHER' will be saved. If 'alarmId' or 'userId' specified in body it will be ignored.\n\nAvailable for users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority."
operationId: saveAlarmComment
parameters:
- name: alarmId
in: path
description: A string value representing the alarm id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
requestBody:
description: A JSON value representing the comment.
content:
application/json:
schema:
$ref: '#/components/schemas/AlarmComment'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AlarmComment'
/api/alarm/{alarmId}/clear:
post:
tags:
- alarm-controller
summary: Clear Alarm (clearAlarm)
description: 'Clear the Alarm. Once cleared, the ''clear_ts'' field will be set to current timestamp and special rule chain event ''ALARM_CLEAR'' will be generated. Referencing non-existing Alarm
Id will cause an error.
Available for users with ''TENANT_ADMIN'' or ''CUSTOMER_USER'' authority.'
operationId: clearAlarm
parameters:
- name: alarmId
in: path
description: A string value representing the alarm id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AlarmInfo'
/api/alarm/{alarmId}/assign/{assigneeId}:
post:
tags:
- alarm-controller
summary: Assign/Reassign Alarm (assignAlarm)
description: 'Assign the Alarm. Once assigned, the ''assign_ts'' field will be set to current timestamp and special rule chain event ''ALARM_ASSIGNED'' (or ALARM_REASSIGNED in case of assigning already
assigned alarm) will be generated. Referencing non-existing Alarm Id will cause an error.
Available for users with ''TENANT_ADMIN'' or ''CUSTOMER_USER'' authority.'
operationId: assignAlarm
parameters:
- name: alarmId
in: path
description: A string value representing the alarm id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
- name: assigneeId
in: path
description: A string value representing the user id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Alarm'
/api/alarm/{alarmId}/ack:
post:
tags:
- alarm-controller
summary: Acknowledge Alarm (ackAlarm)
description: 'Acknowledge the Alarm. Once acknowledged, the ''ack_ts'' field will be set to current timestamp and special rule chain event ''ALARM_ACK'' will be generated. Referencing non-existing
Alarm Id will cause an error.
Available for users with ''TENANT_ADMIN'' or ''CUSTOMER_USER'' authority.'
operationId: ackAlarm
parameters:
- name: alarmId
in: path
description: A string value representing the alarm id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AlarmInfo'
/api/v2/alarms:
get:
tags:
- alarm-controller
summary: Get All Alarms (getAllAlarmsV2)
description: "Returns a page of alarms that belongs to the current user owner. If the user has the authority of 'Tenant Administrator', the server returns alarms that belongs to the tenant of current\
\ user. If the user has the authority of 'Customer User', the server returns alarms that belongs to the customer of current user. You can specify parameters to filter the results. The result is\
\ wrapped with PageData object that allows you to iterate over result set using pagination. See response schema for more details. \n\nAvailable for users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority."
operationId: getAllAlarmsV2
parameters:
- name: statusList
in: query
description: A list of string values separated by comma ',' representing one of the AlarmSearchStatus enumeration value
required: false
schema:
type: array
items:
type: string
enum:
- ANY
- ACTIVE
- CLEARED
- ACK
- UNACK
- name: severityList
in: query
description: A list of string values separated by comma ',' representing one of the AlarmSeverity enumeration value
required: false
schema:
type: array
items:
type: string
enum:
- CRITICAL
- MAJOR
- MINOR
- WARNING
- INDETERMINATE
- name: typeList
in: query
description: A list of string values separated by comma ',' representing alarm types
required: false
schema:
type: array
items:
type: string
- name: assigneeId
in: query
description: A string value representing the assignee user id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: false
schema:
type: string
- name: pageSize
in: query
description: Maximum amount of entities in a one page
required: true
schema:
type: integer
format: int32
- name: page
in: query
description: Sequence number of page starting from 0
required: true
schema:
type: integer
format: int32
- name: textSearch
in: query
description: 'The case insensitive ''substring'' filter based on of next alarm fields: type, severity or status'
required: false
schema:
type: string
- name: sortProperty
in: query
description: Property of entity to sort by
required: false
schema:
type: string
enum:
- createdTime
- startTs
- endTs
- type
- ackTs
- clearTs
- severity
- status
- name: sortOrder
in: query
description: Sort order. ASC (ASCENDING) or DESC (DESCENDING)
required: false
schema:
type: string
enum:
- ASC
- DESC
- name: startTime
in: query
description: 'The start timestamp in milliseconds of the search time range over the Alarm class field: ''createdTime''.'
required: false
schema:
type: integer
format: int64
- name: endTime
in: query
description: 'The end timestamp in milliseconds of the search time range over the Alarm class field: ''createdTime''.'
required: false
schema:
type: integer
format: int64
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PageDataAlarmInfo'
/api/v2/alarm/{entityType}/{entityId}:
get:
tags:
- alarm-controller
summary: Get Alarms (getAlarmsV2)
description: "Returns a page of alarms for the selected entity. You can specify parameters to filter the results. The result is wrapped with PageData object that allows you to iterate over result\
\ set using pagination. See response schema for more details. \n\nAvailable for users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority."
operationId: getAlarmsV2
parameters:
- name: entityType
in: path
description: A string value representing the entity type. For example, 'DEVICE'
required: true
schema:
type: string
- name: entityId
in: path
description: A string value representing the entity id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
- name: statusList
in: query
description: A list of string values separated by comma ',' representing one of the AlarmSearchStatus enumeration value
required: false
schema:
type: array
items:
type: string
enum:
- ANY
- ACTIVE
- CLEARED
- ACK
- UNACK
- name: severityList
in: query
description: A list of string values separated by comma ',' representing one of the AlarmSeverity enumeration value
required: false
schema:
type: array
items:
type: string
enum:
- CRITICAL
- MAJOR
- MINOR
- WARNING
- INDETERMINATE
- name: typeList
in: query
description: A list of string values separated by comma ',' representing alarm types
required: false
schema:
type: array
items:
type: string
- name: assigneeId
in: query
description: A string value representing the assignee user id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: false
schema:
type: string
- name: pageSize
in: query
description: Maximum amount of entities in a one page
required: true
schema:
type: integer
format: int32
- name: page
in: query
description: Sequence number of page starting from 0
required: true
schema:
type: integer
format: int32
- name: textSearch
in: query
description: 'The case insensitive ''substring'' filter based on of next alarm fields: type, severity or status'
required: false
schema:
type: string
- name: sortProperty
in: query
description: Property of entity to sort by
required: false
schema:
type: string
enum:
- createdTime
- startTs
- endTs
- type
- ackTs
- clearTs
- severity
- status
- name: sortOrder
in: query
description: Sort order. ASC (ASCENDING) or DESC (DESCENDING)
required: false
schema:
type: string
enum:
- ASC
- DESC
- name: startTime
in: query
description: 'The start timestamp in milliseconds of the search time range over the Alarm class field: ''createdTime''.'
required: false
schema:
type: integer
format: int64
- name: endTime
in: query
description: 'The end timestamp in milliseconds of the search time range over the Alarm class field: ''createdTime''.'
required: false
schema:
type: integer
format: int64
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PageDataAlarmInfo'
/api/alarms:
get:
tags:
- alarm-controller
summary: Get All Alarms (getAllAlarms)
description: "Returns a page of alarms that belongs to the current user owner. If the user has the authority of 'Tenant Administrator', the server returns alarms that belongs to the tenant of current\
\ user. If the user has the authority of 'Customer User', the server returns alarms that belongs to the customer of current user. Specifying both parameters 'searchStatus' and 'status' at the same\
\ time will cause an error. You can specify parameters to filter the results. The result is wrapped with PageData object that allows you to iterate over result set using pagination. See response\
\ schema for more details. \n\nAvailable for users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority."
operationId: getAllAlarms
parameters:
- name: searchStatus
in: query
description: A string value representing one of the AlarmSearchStatus enumeration value
required: false
schema:
type: string
enum:
- ANY
- ACTIVE
- CLEARED
- ACK
- UNACK
- name: status
in: query
description: A string value representing one of the AlarmStatus enumeration value
required: false
schema:
type: string
enum:
- ACTIVE_UNACK
- ACTIVE_ACK
- CLEARED_UNACK
- CLEARED_ACK
- name: assigneeId
in: query
description: A string value representing the assignee user id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: false
schema:
type: string
- name: pageSize
in: query
description: Maximum amount of entities in a one page
required: true
schema:
type: integer
format: int32
- name: page
in: query
description: Sequence number of page starting from 0
required: true
schema:
type: integer
format: int32
- name: textSearch
in: query
description: 'The case insensitive ''substring'' filter based on of next alarm fields: type, severity or status'
required: false
schema:
type: string
- name: sortProperty
in: query
description: Property of entity to sort by
required: false
schema:
type: string
enum:
- createdTime
- startTs
- endTs
- type
- ackTs
- clearTs
- severity
- status
- name: sortOrder
in: query
description: Sort order. ASC (ASCENDING) or DESC (DESCENDING)
required: false
schema:
type: string
enum:
- ASC
- DESC
- name: startTime
in: query
description: 'The start timestamp in milliseconds of the search time range over the Alarm class field: ''createdTime''.'
required: false
schema:
type: integer
format: int64
- name: endTime
in: query
description: 'The end timestamp in milliseconds of the search time range over the Alarm class field: ''createdTime''.'
required: false
schema:
type: integer
format: int64
- name: fetchOriginator
in: query
description: 'A boolean value to specify if the alarm originator name will be filled in the AlarmInfo object field: ''originatorName'' or will returns as null.'
required: false
schema:
type: boolean
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PageDataAlarmInfo'
/api/alarm/{entityType}/{entityId}:
get:
tags:
- alarm-controller
summary: Get Alarms (getAlarms)
description: "Returns a page of alarms for the selected entity. Specifying both parameters 'searchStatus' and 'status' at the same time will cause an error. You can specify parameters to filter the\
\ results. The result is wrapped with PageData object that allows you to iterate over result set using pagination. See response schema for more details. \n\nAvailable for users with 'TENANT_ADMIN'\
\ or 'CUSTOMER_USER' authority."
operationId: getAlarms
parameters:
- name: entityType
in: path
description: A string value representing the entity type. For example, 'DEVICE'
required: true
schema:
type: string
- name: entityId
in: path
description: A string value representing the entity id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
- name: searchStatus
in: query
description: A string value representing one of the AlarmSearchStatus enumeration value
required: false
schema:
type: string
enum:
- ANY
- ACTIVE
- CLEARED
- ACK
- UNACK
- name: status
in: query
description: A string value representing one of the AlarmStatus enumeration value
required: false
schema:
type: string
enum:
- ACTIVE_UNACK
- ACTIVE_ACK
- CLEARED_UNACK
- CLEARED_ACK
- name: assigneeId
in: query
description: A string value representing the assignee user id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: false
schema:
type: string
- name: pageSize
in: query
description: Maximum amount of entities in a one page
required: true
schema:
type: integer
format: int32
- name: page
in: query
description: Sequence number of page starting from 0
required: true
schema:
type: integer
format: int32
- name: textSearch
in: query
description: 'The case insensitive ''substring'' filter based on of next alarm fields: type, severity or status'
required: false
schema:
type: string
- name: sortProperty
in: query
description: Property of entity to sort by
required: false
schema:
type: string
enum:
- createdTime
- startTs
- endTs
- type
- ackTs
- clearTs
- severity
- status
- name: sortOrder
in: query
description: Sort order. ASC (ASCENDING) or DESC (DESCENDING)
required: false
schema:
type: string
enum:
- ASC
- DESC
- name: startTime
in: query
description: 'The start timestamp in milliseconds of the search time range over the Alarm class field: ''createdTime''.'
required: false
schema:
type: integer
format: int64
- name: endTime
in: query
description: 'The end timestamp in milliseconds of the search time range over the Alarm class field: ''createdTime''.'
required: false
schema:
type: integer
format: int64
- name: fetchOriginator
in: query
description: 'A boolean value to specify if the alarm originator name will be filled in the AlarmInfo object field: ''originatorName'' or will returns as null.'
required: false
schema:
type: boolean
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PageDataAlarmInfo'
/api/alarm/{alarmId}:
get:
tags:
- alarm-controller
summary: Get Alarm (getAlarmById)
description: 'Fetch the Alarm object based on the provided Alarm Id. If the user has the authority of ''Tenant Administrator'', the server checks that the originator of alarm is owned by the same
tenant. If the user has the authority of ''Customer User'', the server checks that the originator of alarm belongs to the customer. '
operationId: getAlarmById
parameters:
- name: alarmId
in: path
description: A string value representing the alarm id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Alarm'
delete:
tags:
- alarm-controller
summary: Delete Alarm (deleteAlarm)
description: 'Deletes the Alarm. Referencing non-existing Alarm Id will cause an error.
Available for users with ''TENANT_ADMIN'' or ''CUSTOMER_USER'' authority.'
operationId: deleteAlarm
parameters:
- name: alarmId
in: path
description: A string value representing the alarm id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: boolean
/api/alarm/types:
get:
tags:
- alarm-controller
summary: Get Alarm Types (getAlarmTypes)
description: Returns a set of unique alarm types based on alarms that are either owned by the tenant or assigned to the customer which user is performing the request.
operationId: getAlarmTypes
parameters:
- name: pageSize
in: query
description: Maximum amount of entities in a one page
required: true
schema:
type: integer
format: int32
- name: page
in: query
description: Sequence number of page starting from 0
required: true
schema:
type: integer
format: int32
- name: textSearch
in: query
description: 'The case insensitive ''substring'' filter based on of next alarm fields: type, severity or status'
required: false
schema:
type: string
- name: sortOrder
in: query
description: Sort order. ASC (ASCENDING) or DESC (DESCENDING)
required: false
schema:
type: string
enum:
- ASC
- DESC
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PageDataEntitySubtype'
/api/alarm/info/{alarmId}:
get:
tags:
- alarm-controller
summary: Get Alarm Info (getAlarmInfoById)
description: 'Fetch the Alarm Info object based on the provided Alarm Id. If the user has the authority of ''Tenant Administrator'', the server checks that the originator of alarm is owned by the
same tenant. If the user has the authority of ''Customer User'', the server checks that the originator of alarm belongs to the customer. Alarm Info is an extension of the default Alarm object that
also contains name of the alarm originator.
Available for users with ''TENANT_ADMIN'' or ''CUSTOMER_USER'' authority.'
operationId: getAlarmInfoById
parameters:
- name: alarmId
in: path
description: A string value representing the alarm id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AlarmInfo'
/api/alarm/highestSeverity/{entityType}/{entityId}:
get:
tags:
- alarm-controller
summary: Get Highest Alarm Severity (getHighestAlarmSeverity)
description: 'Search the alarms by originator (''entityType'' and entityId'') and optional ''status'' or ''searchStatus'' filters and returns the highest AlarmSeverity(CRITICAL, MAJOR, MINOR, WARNING
or INDETERMINATE). Specifying both parameters ''searchStatus'' and ''status'' at the same time will cause an error.
Available for users with ''TENANT_ADMIN'' or ''CUSTOMER_USER'' authority.'
operationId: getHighestAlarmSeverity
parameters:
- name: entityType
in: path
description: A string value representing the entity type. For example, 'DEVICE'
required: true
schema:
type: string
- name: entityId
in: path
description: A string value representing the entity id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
- name: searchStatus
in: query
description: A string value representing one of the AlarmSearchStatus enumeration value
required: false
schema:
type: string
enum:
- ANY
- ACTIVE
- CLEARED
- ACK
- UNACK
- name: status
in: query
description: A string value representing one of the AlarmStatus enumeration value
required: false
schema:
type: string
enum:
- ACTIVE_UNACK
- ACTIVE_ACK
- CLEARED_UNACK
- CLEARED_ACK
- name: assigneeId
in: query
description: A string value representing the assignee user id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: string
enum:
- CRITICAL
- MAJOR
- MINOR
- WARNING
- INDETERMINATE
/api/alarm/{alarmId}/comment/{commentId}:
delete:
tags:
- alarm-comment-controller
summary: Delete Alarm Comment (deleteAlarmComment)
description: 'Deletes the Alarm comment. Referencing non-existing Alarm comment Id will cause an error.
Available for users with ''TENANT_ADMIN'' or ''CUSTOMER_USER'' authority.'
operationId: deleteAlarmComment
parameters:
- name: alarmId
in: path
description: A string value representing the alarm id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
- name: commentId
in: path
description: A string value representing the alarm comment id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
responses:
'200':
description: OK
/api/alarm/{alarmId}/assign:
delete:
tags:
- alarm-controller
summary: Unassign Alarm (unassignAlarm)
description: 'Unassign the Alarm. Once unassigned, the ''assign_ts'' field will be set to current timestamp and special rule chain event ''ALARM_UNASSIGNED'' will be generated. Referencing non-existing
Alarm Id will cause an error.
Available for users with ''TENANT_ADMIN'' or ''CUSTOMER_USER'' authority.'
operationId: unassignAlarm
parameters:
- name: alarmId
in: path
description: A string value representing the alarm id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/thingsboard/refs/heads/main/openapi/thingsboard-alarms-openapi.yml