Trigger API¶

A REST API to lookup/create/update/delete triggers

All trigger API requests require an API bearer token to prove that the client is authorized to make the request.

If the token has OWNER permissions then only triggers owned by the account associated with the token are accessible.

If the token has GROUP or ADMIN privilege then the client can access any trigger owned by any account provided that a valid key is provided that is associated with the requested object. This would normally be an account key or a gateway key for which the trigger is assigned to.

Lookup trigger¶

GET /api/trigger¶

Get trigger attributes for the specified trigger as a JSON object.

Query Parameters:

key (string) – The owner account key. This can be an account key or a gateway key.
trigger (string) – The trigger uuid
indent (int) – optional - pretty print the json output using the indent value. Default is no indent.

Request Headers:

Authorization – Bearer <api-token>
Content-Type – application/json

Status Codes:

200 OK – Request succeeded
400 Bad Request – Parameters are invalid
403 Forbidden – Unauthorized - invalid key or API token
404 Not Found – Invalid trigger id (trigger not found)

GET /api/trigger¶

Get trigger attributes for the all the triggers owned by the specified gateway.

Query Parameters:

key (string) – The owner account key. This can be an account key or a gateway key.
gateway (string) – The mac address of the gateway that owns the trigger.
indent (int) – optional - pretty print the json output using the indent value. Default is no indent.

Request Headers:

Authorization – Bearer <api-token>
Content-Type – application/json

Status Codes:

200 OK – Request succeeded
400 Bad Request – Parameters are invalid
403 Forbidden – Unauthorized - invalid key or API token
404 Not Found – Invalid trigger id (trigger not found)

Example¶

Get a list of triggers for gateway 4016fa0500cd.

http

GET /api/trigger?key=MTAxMDoyMDIw&gateway=4016fa0500cd HTTP/1.1
Host: api.ekmpush.com
Accept: application/json
Authorization: Bearer BZTdu8_5iw62WQuDg4OHIMhG7mcEqJu8VrzHSywCkPk

curl

curl -i -X GET 'https://api.ekmpush.com/api/trigger?key=MTAxMDoyMDIw&gateway=4016fa0500cd' -H "Accept: application/json" -H "Authorization: Bearer BZTdu8_5iw62WQuDg4OHIMhG7mcEqJu8VrzHSywCkPk"

response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "triggers": [
    {
      "trigger_uuid": "1c27d0dcefc811eb90b27de8d650408c",
      "trigger_name": "test",
      "conditions": [
        {
          "condition_type": "data",
          "field": "kWh_Tot",
          "source": "meter",
          "duration": "0",
          "source_id": "000350000900",
          "continuous": false,
          "hysteresis": "60",
          "threshold_test": "rise_eq",
          "threshold_value": "10"
        }
      ],
      "actions": [
        {
          "params": {
            "relay": "relay_1",
            "status": "close",
            "duration": 1
          },
          "target": "meter",
          "command": "setRelay",
          "target_id": "000350000900"
        }
      ],
      "enabled": true,
      "created_at": "2021-07-28T17:20:31.824621+00:00",
      "updated_at": "2021-07-28T17:20:31.824621+00:00"
    }
  ]
}

Create Trigger¶

POST /api/trigger¶

Create a new trigger

Query Parameters:

key (string) – The owner account key. This can be any key associated with the account.
gateway (string) – The mac address of the gateway that owns the trigger.

Request JSON Object:

trigger (jsonobj) – The trigger attributes

Request Headers:

Authorization – Bearer <api-token>
Content-Type – application/json

Status Codes:

201 Created – Request succeeded, trigger created
400 Bad Request – Parameters are invalid
403 Forbidden – Unauthorized - invalid key or API token
500 Internal Server Error – Internal error (ie unable to create trigger)

The trigger JSON will be returned as JSON in the response body if successful (status 201).

In case of an error (response code 400) the response JSON will contain an error attribute with a string value describing the error.

Trigger JSON Attributes¶

trigger_name:: (string) The name of the trigger
enabled:: (boolean) Enable trigger if true (default)
conditions:: (jsonobj) List of conditions
actions:: (jsonobj) List of actions

Read-only attributes:

trigger_uuid:: (string) A unique identifier
created_at:: (string) The date/time of creation (ISO format)
updated_at:: (string) The date/time of last update/modify (ISO format)

Conditions¶

There are two types of conditions: Data and RRULE (recurrence rule). Data conditions are for testing field data values and RRULE conditions are for triggering actions at a specified time or recurrence.

type:: (string) Condition type (ie “data”, or “rrule”)

Data Condition¶

source:

(string) The data source device type (ie “meter”, “iostack”)

source_id:

(string) The source id (ie meter address).

field:

(string) The name of the field to monitor.

threshold_value:

(float) The threshold value to compare with.

threshold_test:

(string) The threshold value test.

“==”: Data field value equals threshold value

“!=”: Data field value not equals threshold value

“>=”: Data field value greater than or equals threshold value

“<=”: Data field value less than or equals threshold value

“>”: Data field value greater than threshold value

“<”: Data field value less than threshold value

duration:

(float) Optional - Minimum duration in seconds of the test condition (default 0).

hysteresis:

(float) Optional - Minimum time in seconds before the next test (default 60).

continuous:

(boolean) Optional - Keep firing as long as condition is satisfied (default false).

tolerance:

(float) Optional - Floating point comparison tolerance/epsilon (default 1e-6).

Example:

Trigger when meter 0000300001317 field kWh_Tot rises above 1000

"conditions": [
  {
    "type": "data",
    "source": "meter",
    "source_id": "0000300001317",
    "field": "kWh_Tot",
    "threshold_value": "1000",
    "threshold_test": "rise_gt",
  }
]

RRULE Condition¶

rrule:: (string) Recurrence rule (see: iCalendar RFC-5545)

Note: All date-times are UTC (no offset).

Example RRULE condition: Starting on 7/2/2021 17:32 UTC, trigger every day at 00:35:00 UTC

"conditions": [
  {
    "type": "rrule",
    "rrule": "DTSTART:20210702T173200\nRRULE:FREQ=DAILY;BYHOUR=0;BYMINUTE=35;BYSECOND=0"
  }
]

There are some decent open source RRULE generator demos you can use to build the RRULE strings:

rrule.js

React RRULE

Actions¶

Actions can be a meter setting command or an email notification.

See EKM Meter Commands.

Email notifications have some limitations to limit potential abuse:

They can only be specified for Data conditions.

The email “to” address will always be the verified email address of the account holder.

The subject and body will be auto-generated based on the condition that was satisfied.

Example action: Send email notification

"actions": [
  {
    "target": "gateway",
    "command": "sendEmail"
  }
]

Example action: Close relay one on meter 000350000900

"actions": [
  {
    "target": "meter",
    "target_id": "000350000900"
    "command": "setRelay",
    "params": {
      "relay": "relay_1",
      "status": "close",
      "duration": 1
    },
  }
]

Example¶

http

POST /api/trigger?key=MTAxMDoyMDIw&gateway=4016fa0500cd HTTP/1.1
Host: api.ekmpush.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer BZTdu8_5iw62WQuDg4OHIMhG7mcEqJu8VrzHSywCkPk

{
  "trigger": {
    "trigger_name": "Some trigger",
    "enabled": true,
    "conditions": [
      {
        "type": "data",
        "field": "kWh_Tot",
        "source": "meter",
        "duration": "0",
        "source_id": "000350000900",
        "continuous": false,
        "hysteresis": "60",
        "threshold_test": "rise_eq",
        "threshold_value": "10"
      }
    ],
    "actions": [
      {
        "target": "meter",
        "target_id": "000350000900",
        "command": "setRelay",
        "params": {
          "relay": "relay_1",
          "status": "close",
          "duration": 1
        }
      }
    ]
  }
}

curl

curl -i -X POST 'https://api.ekmpush.com/api/trigger?key=MTAxMDoyMDIw&gateway=4016fa0500cd' -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer BZTdu8_5iw62WQuDg4OHIMhG7mcEqJu8VrzHSywCkPk" --data-raw '{"trigger": {"actions": [{"target": "meter", "target_id": "000350000900", "command": "setRelay", "params": {"relay": "relay_1", "status": "close", "duration": 1}}], "conditions": [{"type": "data", "field": "kWh_Tot", "source": "meter", "duration": "0", "source_id": "000350000900", "continuous": false, "hysteresis": "60", "threshold_test": "rise_eq", "threshold_value": "10"}], "enabled": true, "trigger_name": "Some trigger"}}'

response

HTTP/1.1 201 OK
Content-Type: application/json

{
  "trigger": {
    "trigger_uuid": "1c27d0dcefc811eb90b27de8d650408c",
    "trigger_name": "test",
    "enabled": true,
    "created_at": "2021-07-28T17:20:31.824621+00:00",
    "updated_at": "2021-07-28T17:20:31.824621+00:00",
    "conditions": [
      {
        "type": "data",
        "field": "kWh_Tot",
        "source": "meter",
        "duration": "0",
        "source_id": "000350000900",
        "continuous": false,
        "hysteresis": "60",
        "threshold_test": "rise_eq",
        "threshold_value": "10"
      }
    ],
    "actions": [
     {
        "target": "meter",
        "target_id": "000350000900",
        "command": "setRelay",
        "params": {
          "relay": "relay_1",
          "status": "close",
          "duration": 1
        }
      }
    ]
  }
}

Modify trigger¶

PUT /api/trigger¶

Modify an existing trigger

Query Parameters:

key (string) – The owner account key. This can be any key associated with the account.

Request JSON Object:

trigger (jsonobj) – The trigger attributes

Request Headers:

Authorization – Bearer <api-token>
Content-Type – application/json

Status Codes:

200 OK – Request succeeded, trigger modified
400 Bad Request – Parameters are invalid
403 Forbidden – Unauthorized - invalid key or API token
404 Not Found – Invalid trigger id (trigger not found)
500 Internal Server Error – Internal error (ie unable to modify trigger)

The trigger JSON will be returned as JSON in the response body if successful (status 201).

In case of an error (response code 400) the response JSON will contain an error attribute with a string value describing the error.

Example¶

http

PUT /api/trigger?key=MTAxMDoyMDIw HTTP/1.1
Host: api.ekmpush.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer BZTdu8_5iw62WQuDg4OHIMhG7mcEqJu8VrzHSywCkPk

{
  "trigger": {
      "trigger_uuid": "1c27d0dcefc811eb90b27de8d650408c",
      "trigger_name": "New trigger name"
  }
}

curl

curl -i -X PUT 'https://api.ekmpush.com/api/trigger?key=MTAxMDoyMDIw' -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer BZTdu8_5iw62WQuDg4OHIMhG7mcEqJu8VrzHSywCkPk" --data-raw '{"trigger": {"trigger_name": "New trigger name", "trigger_uuid": "1c27d0dcefc811eb90b27de8d650408c"}}'

response

HTTP/1.1 201 OK
Content-Type: application/json

{
  "trigger": {
    "trigger_uuid": "1c27d0dcefc811eb90b27de8d650408c",
    "trigger_name": "New trigger name",
    "enabled": true,
    "created_at": "2021-07-28T17:20:31.824621+00:00",
    "updated_at": "2021-07-28T17:20:31.824621+00:00",
    "conditions": [
      {
        "type": "data",
        "field": "kWh_Tot",
        "source": "meter",
        "duration": "0",
        "source_id": "000350000900",
        "continuous": false,
        "hysteresis": "60",
        "threshold_test": "rise_eq",
        "threshold_value": "10"
      }
    ],
    "actions": [
      {
        "target": "meter",
        "target_id": "000350000900"
        "command": "setRelay",
        "params": {
          "relay": "relay_1",
          "status": "close",
          "duration": 1
        },
      }
    ]
  }
}

Delete trigger¶

DELETE /api/trigger¶

Delete an existing trigger

Query Parameters:

key (string) – The owner account key. This can be any key associated with the account.

Request JSON Object:

trigger_uuid (jsonobj) – The trigger id

Request Headers:

Authorization – Bearer <api-token>
Content-Type – application/json

Status Codes:

200 OK – Request succeeded, trigger modified
400 Bad Request – Parameters are invalid
403 Forbidden – Unauthorized - invalid key or API token
404 Not Found – Invalid trigger id (trigger not found)
500 Internal Server Error – Internal error (ie unable to modify trigger)

Example¶

http

DELETE /api/trigger?key=MTAxMDoyMDIw HTTP/1.1
Host: api.ekmpush.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer BZTdu8_5iw62WQuDg4OHIMhG7mcEqJu8VrzHSywCkPk

{
  "trigger_uuid": "1c27d0dcefc811eb90b27de8d650408c"
}

curl

curl -i -X DELETE 'https://api.ekmpush.com/api/trigger?key=MTAxMDoyMDIw' -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer BZTdu8_5iw62WQuDg4OHIMhG7mcEqJu8VrzHSywCkPk" --data-raw '{"trigger_uuid": "1c27d0dcefc811eb90b27de8d650408c"}'

response

HTTP/1.1 201 OK
Content-Type: application/json

{}

Trigger API¶

Lookup trigger¶

Example¶

Create Trigger¶

Trigger JSON Attributes¶

Conditions¶

Data Condition¶

RRULE Condition¶

Actions¶

Example¶

Modify trigger¶

Example¶

Delete trigger¶

Example¶

Table of Contents

Previous topic

This Page