Time Series Database

Time Series Database (TSDB) Smart Module endpoints for managing simple time series or time series collections, and for retrieving data stored in TSDB for this home.

Endpoints

The Simple Time Series object

  • idstring

    Time Series ID. Must be unique within each home. Must be 1 or more alphanumeric characters and may contain dashes ('-'), underscores ('_'), and colons (':') may be used after the first character but must be followed by 1+ alphanumeric characters.

  • homeIdinteger

    Home that this time series belongs to.

  • moduleIdstring

    ID of Smart Module that created this time series.

  • timeZonestring

    If present, time series is associated with a time zone that is not UTC. This should be a time zone name defined in the IANA TZ Database.

The Time Series Collection object

  • idstring

    Time Series Collection ID. Must be unique within each home. Must be 1 or more alphanumeric characters and may contain dashes ('-'), underscores ('_'), and colons (':') may be used after the first character but must be followed by 1+ alphanumeric characters.

  • homeIdinteger

    Home that this collection belongs to.

  • moduleIdstring

    ID of Smart Module that created this collection.

  • timeZonestring

    If present, collection is associated with a time zone that is not UTC. This should be a time zone name defined in the IANA TZ Database.

  • valueNamesarray

    List of unique Identifiers of numerical fields in collection.

  • tagNamesarray

    List of unique Identifiers of string tags in collection.

The Time Series Export Request object

  • seriesIdsarray

    Array of series IDs whose data are to be exported.

  • collectionIdsarray

    Array of collection IDs whose data are to be exported.

  • fileNamesarray

    Optional field to specify export file names. It should correspond to seriesIds/collectionIds in number and order. If omitted, series or collection IDs will be used in the file names.

  • beginstring| format is date-time

    The beginning timestamp of the export time range (in RFC3339).

  • endstring| format is data-time

    The ending timestamp of the export time range (in RFC3339).

  • includeHeaderboolean

    If true, each exported CSV file will start with a header. Used only when exporting collections.

The Home-Scoped Monitor object

  • idinteger

    Identifier of monitor

  • projectIdinteger

    Project that this monitor belongs to

  • moduleIdstring

    Smart Module that this monitor belongs to

  • homeIdinteger

    Home that this monitor belongs to

  • namestring

    Monitor name

  • descriptionstring

    Monitor description

  • evaluationDelayinteger

    How long the monitor evaluation should be delayed

  • conditionobject

    Monitor Condition object

  • incidentCustomDescriptionsobject

    Incident Custom Descriptions object

  • enabledboolean

    Whether this monitor is enabled

  • modificationTimestring| format is date-time

    Timestamp of modification.

  • issuestring

    issue of monitor setting

  • isAlertingboolean

    If true, some or all of the monitoring targets are in alert state

The Home-Scoped Monitor For Writing Operations object

  • namestring

    Monitor name

  • descriptionstring

    Monitor description

  • evaluationDelayinteger

    How long the monitor evaluation should be delayed; if this field is omitted when monitor is created, default value 0 will be applied

  • conditionobject

    Monitor Condition object

  • incidentCustomDescriptionsobject

    Incident Custom Descriptions object

  • enabledboolean

    Whether this monitor is enabled

The Incident object

  • incidentTypestring| options are alert, recovery

    Type of this incident

  • descriptionstring

    Description of this incident

  • projectIdinteger

    Project that this incident belongs to

  • moduleIdstring

    Smart Module that this incident belongs to

  • homeIdinteger

    Home that this monitor belongs to

  • monitorIdinteger

    Monitor that created this incident

  • monitorSnapshotobject

    Monitor Snapshot object which is the snapshot of the monitor when this incident was created

  • evaluationTimeRangeobject

    Time Range object that represents the time range against which the monitor evaluated the data points when creating this incident

  • creationTimestring

    Timestamp of creation of this incident.

The Custom descriptions for incident object

  • alertstring

    Custom description for alert incident. If not set, default description will be 'ALERT: ${monitor.name}'

  • recoverystring

    Custom description for recovery incident. If not set, default description will be 'RECOVERY: ${monitor.name}'

The Time Series Heartbeat Condition object

  • conditionTypestring

    Currently, the only supported type is timeSeriesHeartbeat.

  • seriesIdstring

    Time Series ID to be monitored.

  • intervalinteger

    Duration of time (second) how often data points are expected to appear in the time series. It should be longer than 60 seconds at least.

The Time Series Threshold Condition object

  • conditionTypestring

    Currently, the only supported type is timeSeriesThreshold

  • seriesIdstring

    Time Series ID to be monitored

  • intervalinteger

    How often (in seconds) the monitoring condition is evaluated

  • operatorstring| options are lessThan, lessThanOrEqualTo, equal, notEqual, greaterThanOrEqualTo, greaterThan

    The operator to compare the threshold value and monitored value

  • thresholdnumber

    Threshold value against which the monitor evaluates whether the data point has breached the condition

  • dataPointsEvaluationPolicystring| options are consecutive, total

    How to count the breaching data points

  • numberOfBreachingDataPointsToAlertinteger

    Number of breaching data points before an alert is triggered

  • dataPointsDurationinteger

    Expected duration of time (in seconds) between two data points

  • missingDataPointPolicystring| options are ignore, breaching, notBreaching

    How to treat missing data

The Snapshot of the monitor which are embedded in an incident object

  • namestring

    Monitor name

  • descriptionstring

    Monitor description

  • evaluationDelayinteger

    How long the monitor evaluation should be delayed

  • conditionobject

    Monitor Condition object

  • incidentCustomDescriptionsobject

    Incident Custom Descriptions object

Export time series data

Endpoint
post /homes/{homeId}/smartModules/{moduleId}/export
Description

Export the data in one or more time series or time series collections. The request body must be a valid Time Series Export Request object. Use the seriesIds field in the request object to export time series, or the collectionIds field to export collections.

Path Parameters

  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200The URLs for downloading the exported data are returned.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid request parameters.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

{
  "seriesIds": [
    "rm1_humidity",
    "rm1_temperature"
  ],
  "begin": "2019-05-10T10:00:00Z",
  "end": "2019-05-11T13:00:00Z"
}

Get all time series

Endpoint
get /homes/{homeId}/smartModules/{moduleId}/timeSeries
Description

Get the list of all time series being stored for this home.

Path Parameters

  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200An array of time series objects are returned.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Create a time series

Endpoint
post /homes/{homeId}/smartModules/{moduleId}/timeSeries
Description

Create a new time series for this home. Normally a time series is automatically created when data points are first injected. However, such time series are automatically defaulted to the UTC time zone. Time series that are meant to be in a specific time zone should be explicitly created with this endpoint ahead of time, before any data points are injected. The request body must contain the id and timeZone fields.

Path Parameters

  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Response
  • 201Time series successfully created.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

{
  "id": "room1_humidity",
  "timeZone": "Asia/Tokyo"
}

Get time series

Endpoint
get /homes/{homeId}/smartModules/{moduleId}/timeSeries/{seriesId}
Description

Get the information of a specific time series.

Path Parameters

  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

  • seriesId

    string

    required

    Series ID. It must be unique per home.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200The requested time series object is returned.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested timeSery does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

{
  "id": "room1-temperature",
  "homeId": 2233,
  "moduleId": "sensor_data",
  "timeZone": "Europe/Berlin"
}

Delete time series

Endpoint
delete /homes/{homeId}/smartModules/{moduleId}/timeSeries/{seriesId}
Description

Delete a specific time series and all its data.

Path Parameters

  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

  • seriesId

    string

    required

    Series ID. It must be unique per home.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Response
  • 204Time series successfully deleted.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The required timeSery does not exist or is not accessible.
  • 409The timeSery cannot be deleted because it is being used by another part of the system.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Get time series data

Endpoint
get /homes/{homeId}/smartModules/{moduleId}/timeSeries/{seriesId}/data
Description

Get the time series data specified by series ID. Use the begin and end parameters to fetch values by time range, with the proper time resolution automatically applied. Use the ts and limit parameters to fetch a specific number of data points before or after a point in time.

Path Parameters

  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

  • seriesId

    string

    required

    Series ID. It must be unique per home.

Query Parameters

  • begin

    string

    required

    The beginning of the time series data. The format follows RFC3339.

  • end

    string

    required

    The end of the time series data. The format follows RFC3339.

  • resolution

    string

    required

    The resolution of time bucket. The string must be either '5sec', '15sec', '1min', '10min', '1hour', '1day', '1week', '1month'. Decided automatically based on the timespan between "begin" and "end" parameters if not provided.

  • aggregation

    string

    required

    Aggregation function. The string must be either 'avg', 'min', 'max', 'sum' or 'count'. 'avg' is chosen if not provided.

  • ts

    string

    required

    The point in time (in RFC3339) to fetch data points from.

  • limit

    integer

    required

    If positive, this is the maximum number of data points at and after ts to be returned. If negative, this is the maximum number of data points before ts to be returned.

  • skipNullRecords

    boolean

    required

    If true, skip any records whose values are all null. False by default.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200The requested time series data points are returned.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested datum does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

{
  "seriesId": "room1-temperature",
  "begin": "2019-04-11T07:51:46.712Z",
  "end": "2020-01-29T01:26:08.101Z",
  "aggregation": "avg",
  "resolution": "1day",
  "data": [
    ["2019-04-11T00:00:00Z", 22.97349639133924],
    ["2019-04-12T00:00:00Z", 22.916217542079057],
    ["2019-04-13T00:00:00Z", 21.939217256214157],
    ["2019-04-14T00:00:00Z", 21.668999574649146],
    ["2019-04-15T00:00:00Z", 23.01144695453247],
    ["2019-04-16T00:00:00Z", 23.877712361878466],
    ["2019-04-17T00:00:00Z", 24.251540345449843],
    ["2019-04-18T00:00:00Z", 23.900341664030382],
    ["2019-04-19T00:00:00Z", 23.579976112920807]
  ]
}

Delete time series data

Endpoint
delete /homes/{homeId}/smartModules/{moduleId}/timeSeries/{seriesId}/data
Description

Delete data points of a time series that fall within a given time range. If only the begin parameter is specified, all data timestamped after begin will be deleted. If only the end parameter is specified, all data timestamped before end will be deleted.

Path Parameters

  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

  • seriesId

    string

    required

    Series ID. It must be unique per home.

Query Parameters

  • begin

    string

    required

    The beginning of the time range. The format follows RFC3339.

  • end

    string

    required

    The end of the time range. The format follows RFC3339.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Response
  • 204The data points have been successfully deleted.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The required datum does not exist or is not accessible.
  • 409The datum cannot be deleted because it is being used by another part of the system.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Get time series time range

Endpoint
get /homes/{homeId}/smartModules/{moduleId}/timeSeries/{seriesId}/timeRange
Description

Get the timestamp of the first and last data points in the specified time series.

Path Parameters

  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

  • seriesId

    string

    required

    Series ID. It must be unique per home.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200The requested time range is returned.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested timeRange does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

{
  "seriesId": "room1-temperature",
  "begin": "2018-12-11T17:00:22Z",
  "end": "2020-01-29T01:26:08.101Z"
}

Get all time series collections

Endpoint
get /homes/{homeId}/smartModules/{moduleId}/collections
Description

Get the list of all time series collections being stored for this home.

Path Parameters

  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200An array of time series collections are returned.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Create a time series collection

Endpoint
post /homes/{homeId}/smartModules/{moduleId}/collections
Description

Create a new time series collection for this home. Normally a collection is automatically created when data points are first injected. However, such collections are automatically defaulted to the UTC time zone. Collections that are meant to be in a specific time zone should be explicitly created with this endpoint ahead of time, before any data points are injected. The request body must contain the id and timeZone fields.

Path Parameters

  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Response
  • 201Collection successfully created.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

{
  "id": "sensor1_measurements",
  "timeZone": "America/New_York"
}

Get time series collection

Endpoint
get /homes/{homeId}/smartModules/{moduleId}/collections/{collectionId}
Description

Get the information of a specific time series collection.

Path Parameters

  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

  • collectionId

    string

    required

    Collection ID. It must be unique per home.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200Info of the requested time series collection is returned.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested collection does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

{
  "id": "room1-metrics",
  "homeId": 2233,
  "moduleId": "sensor_data",
  "timeZone": "Europe/Berlin",
  "valueNames": ["temperature", "humidity", "pressure"],
  "tagNames": ["vendor_id", "occupant"]  
}

Delete time series collection

Endpoint
delete /homes/{homeId}/smartModules/{moduleId}/collections/{collectionId}
Description

Delete a specific collection and all its data.

Path Parameters

  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

  • collectionId

    string

    required

    Collection ID. It must be unique per home.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Response
  • 204Collection successfully deleted.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The required collection does not exist or is not accessible.
  • 409The collection cannot be deleted because it is being used by another part of the system.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Get collection data

Endpoint
get /homes/{homeId}/smartModules/{moduleId}/collections/{collectionId}/data
Description

Get the collection data specified by collection ID. Use the begin and end parameters to fetch entries by time range, with the proper time resolution automatically applied. Use the ts and limit parameters to fetch a specific number of entries before or after a point in time. Use the selectValues parameter to specify which value fields of the collection should be returned. When raw data entries are being fetched, it is possible to use the selectTags parameter to retrieve the tag fields from the entries as well.

Path Parameters

  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

  • collectionId

    string

    required

    Collection ID. It must be unique per home.

Query Parameters

  • begin

    string

    required

    The beginning time of the data entries. The format follows RFC3339.

  • end

    string

    required

    The end time of the data entries. The format follows RFC3339.

  • resolution

    string

    required

    The resolution of time bucket. The string must be either '5sec', '15sec', '1min', '10min', '1hour', '1day', '1week', '1month'. Decided automatically based on the timespan between "begin" and "end" parameters if not provided.

  • aggregation

    string

    required

    Aggregation function. The string must be either 'avg', 'min', 'max', 'sum' or 'count'. 'avg' is chosen if not provided.

  • ts

    string

    required

    The point in time (in RFC3339) to fetch data entries from.

  • limit

    integer

    required

    If positive, this is the maximum number of data entries at and after ts to be returned. If negative, this is the maximum number of data points before ts to be returned.

  • selectValues

    string

    required

    A comma-delimited list of value names. Since each data entry in the collection contains multiple value fields, the fields to be returned must be specified

  • selectTags

    string

    required

    A comma-delimited list of tag names. This is used only when fetching entries with the ts and limit parameters. If data entries contain tags, use this parameter to return the desired tag fields.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200The requested collection data entries are returned.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested datum does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

{
  "collectionId": "room1-metrics",
  "begin": "2019-04-11T07:51:46.712Z",
  "end": "2020-01-29T01:26:08.101Z",
  "aggregation": "avg",
  "resolution": "1day",
  "data": [
    ["2019-04-11T00:00:00Z", 22.97349639133924, 0.66, 772],
    ["2019-04-12T00:00:00Z", 22.916217542079057, 0.77, 899],
    ["2019-04-13T00:00:00Z", 21.939217256214157, 0.80, 502],
    ["2019-04-14T00:00:00Z", 21.668999574649146, 0.50, 888],
    ["2019-04-15T00:00:00Z", 23.01144695453247, 0.55, 890],
    ["2019-04-16T00:00:00Z", 23.877712361878466, 0.63, 792],
    ["2019-04-17T00:00:00Z", 24.251540345449843, 0.45, 662],
    ["2019-04-18T00:00:00Z", 23.900341664030382, 0.80, 705],
    ["2019-04-19T00:00:00Z", 23.579976112920807, 0.78, 780]
  ]
}

Delete collection data

Endpoint
delete /homes/{homeId}/smartModules/{moduleId}/collections/{collectionId}/data
Description

Delete data entries of a time series collection that fall within a given time range. If only the begin parameter is specified, all entries timestamped after begin will be deleted. If only the end parameter is specified, all entries timestamped before end will be deleted.

Path Parameters

  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

  • collectionId

    string

    required

    Collection ID. It must be unique per home.

Query Parameters

  • begin

    string

    required

    The beginning of the time range. The format follows RFC3339.

  • end

    string

    required

    The end of the time range. The format follows RFC3339.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Response
  • 204The data entries have been successfully deleted.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The required datum does not exist or is not accessible.
  • 409The datum cannot be deleted because it is being used by another part of the system.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Get time range of collection data

Endpoint
get /homes/{homeId}/smartModules/{moduleId}/collections/{collectionId}/timeRange
Description

Get the timestamp of the first and last data entries in the specified time series collection.

Path Parameters

  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

  • collectionId

    string

    required

    Collection ID. It must be unique per home.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200The requested time range is returned.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested timeRange does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

{
  "seriesId": "room1-temperature",
  "begin": "2018-12-11T17:00:22Z",
  "end": "2020-01-29T01:26:08.101Z"
}

Get all monitors for a home

Endpoint
get /homes/{homeId}/smartModules/{moduleId}/monitors
Description

Get the list of all monitors for this home.

Path Parameters

  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

Query Parameters

  • skip

    integer

    Number of monitors to skip over.

  • limit

    integer

    Maximum number of monitors to return.

    Default value is 20

    Minimum value is 1

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200An array of monitors are returned.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Create a monitor for a home

Endpoint
post /homes/{homeId}/smartModules/{moduleId}/monitors
Description

Create a monitor for this home.

Path Parameters

  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Request Body

  • enabled

    boolean

    Whether this monitor is enabled

Response
  • 201Monitor successfully created
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

{
  "name": "humidity monitor",
  "description": "humidity monitor",
  "evaluationDelay": 60,
  "condition": {
    "conditionType": "timeSeriesThreshold",
    "seriesId": "room1_humidity",
    "interval": 120
  },
  "enabled": true
}

Get a monitor for a home

Endpoint
get /homes/{homeId}/smartModules/{moduleId}/monitors/{monitorId}
Description

Get the information of a monitor for this home.

Path Parameters

  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

  • monitorId

    string

    required

    Monitor ID

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200Info of the requested monitor is returned.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested monitor does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

{
  "id": 100,
  "projectId": 5432,
  "moduleId": "sensor_data",
  "homeId": 1234,
  "name": "test",
  "description": "test",
  "evaluationDelay": 60,
  "condition": {
    "conditionType": "timeSeriesThreshold",
    "seriesId": "room1_humidity",
    "interval": 120
  },
  "enabled": true,
  "modificationTime": "2020-01-01T12:01:18.105Z",
  "isAlerting": true
}

Update a monitor for a home

Endpoint
patch /homes/{homeId}/smartModules/{moduleId}/monitors/{monitorId}
Description

Update a monitor for this home.

Path Parameters

  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

  • monitorId

    string

    required

    Monitor ID

Request Headers What's this?

  • Authorization

    required

    Must contain API key of the matching user, or a Project API Key with admin permission.

Request Body

  • name

    string

    Monitor name

  • description

    string

    Monitor description

  • evaluationDelay

    integer

    How long the monitor evaluation should be delayed; if this field is omitted when monitor is created, default value 0 will be applied

  • condition

    object

    Monitor Condition object

  • incidentCustomDescriptions

    object

    Incident Custom Descriptions object

  • enabled

    boolean

    Whether this monitor is enabled

Response
  • 204The monitor has been successfully updated.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The requested monitor does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

{
  "name": "humidity monitor",
  "description": "humidity monitor",
  "evaluationDelay": 60,
  "condition": {
    "conditionType": "timeSeriesThreshold",
    "seriesId": "room1_humidity",
    "interval": 120
  },
  "enabled": true
}

Delete a monitor for a home

Endpoint
delete /homes/{homeId}/smartModules/{moduleId}/monitors/{monitorId}
Description

Delete a monitor and all its incidents for this home.

Path Parameters

  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

  • monitorId

    string

    required

    Monitor ID

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Response
  • 204Monitor successfully deleted.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The required monitor does not exist or is not accessible.
  • 409The monitor cannot be deleted because it is being used by another part of the system.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Get all incidents in a home

Endpoint
get /homes/{homeId}/smartModules/{moduleId}/incidents
Description

Get the list of all incidents in this home.

Path Parameters

  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

Query Parameters

  • monitorId

    number

    required

    ID of monitor by which this incident is created

  • skip

    integer

    Number of incidents to skip over (incidents are ordered in descending order by creation time)

  • limit

    integer

    If non-zero, maximum number of incidents to return. limit should be the number between 1 to 100.

    Default value is 20

    Minimum value is 1

Response
  • 200An array of monitors are returned.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

[
  {
    "incidentType": "recovery",
    "description": "RECOVERY: humidity sensor connection is back to normal",
    "projectId": 1234,
    "moduleId": "tsdb",
    "homeId": 100,
    "monitorId": 1347,
    "monitorSnapshot": {
      "name": "humidity sensor heartbeat",
      "description": "",
      "evaluationDelay": 60,
      "condition": {
        "conditionType": "timeSeriesHeartbeat",
        "seriesId": "humidity",
        "interval": 60
      },
      "incidentCustomDescriptions": {
        "alert": "ALERT: check if the humidity sensor is connected",
        "recovery": "RECOVERY: humidity sensor connection is back to normal"
      }
    },
    "evaluationTimeRange": {
      "begin": "2021-03-01T18:08:09Z",
      "end": "2021-03-01T18:09:09Z"
    },
    "creationTime": "2021-03-01T18:10:09Z"
  },
  {
    "incidentType": "alert",
    "description": "ALERT: check if the humidity sensor is connected",
    "projectId": 1234,
    "moduleId": "tsdb",
    "homeId": 100,
    "monitorId": 1347,
    "monitorSnapshot": {
      "name": "humidity sensor heartbeat",
      "description": "",
      "evaluationDelay": 60,
      "condition": {
        "conditionType": "timeSeriesHeartbeat",
        "seriesId": "humidity",
        "interval": 60
      },
      "incidentCustomDescriptions": {
        "alert": "ALERT: check if the humidity sensor is connected",
        "recovery": "RECOVERY: humidity sensor connection is back to normal"
      }
    },
    "evaluationTimeRange": {
      "begin": "2021-03-01T17:00:08Z",
      "end": "2021-03-01T17:01:08Z"
    },
    "creationTime": "2021-03-01T17:02:08Z"
  }
]