Introduction

Base URL

https://edge.onupkeep.com/api/v1

Welcome to UpKeep's Edge API! You can use the Edge API to access your sensor data, manage sensors, create alerts, and much more! Essentially, anything you can do in the Edge web application, you can do with the API.

The Edge API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Reponse format

{
  "meta": {
    "dataFormat": "array"
  },
  "data": [
    {
      "deviceTypeId": 1,
      "companyId": null,
      "deviceProvider": "upkeep",
      "deviceTypeName": "UpKeep Vibration",
      "vendorDeviceTypeId": "95",
      ...
    },
    {
      "deviceTypeId": 2,
      "companyId": null,
      "deviceProvider": "upkeep",
      "deviceTypeName": "UpKeep Temperature",
      "vendorDeviceTypeId": "2",
      ...
    }
  ]
}

All responses will be standard JSON with two keys: meta and data. The meta key includes information about the data (e.g. whether it is a single object or an array of objects) while the data key includes the actual data.

Authentication

# The colon prevents curl from asking for a password.
curl https://edge.onupkeep.com/api/v1/devices \
  -u YOUR_API_KEY:

The Edge API uses API keys to authenticate requests. You can view and create / refresh your API keys on the API tab of the Edge Dashboard. Note that if you refresh your API key, all previous API keys will be invalidated.

API Keys are company specific. In other words, all users across your company will use the same API Key.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas.

Errors

Edge uses conventional HTTP response codes to indicate the success or failure of an API request.

In general: codes in the 2xx range indicate success. Codes in the 4xx range indicate an error occurred due to the information provided (e.g., a required parameter was omitted, a resource is not authorized for writes, etc.). Codes in the 5xx range indicate an error with Edge's servers (these are rare).

Example error codes with messages:

Error Code	Message	Description
400	Bad Request	There was a problem with the input you submitted.
401	Unauthorized	Your API key is missing or invalid.
404	Not Found	The resource you requested does not exist.
500	Internal Server Error	Something went wrong on our end. Try again later.

General concepts

The Edge API data structure centers around devices (devices). Devices are typically sensors, but they can also include gateways and anything else that regularly collects and transmits telemetry data. Each device must have a device type (deviceType). The device type specifies whether a device is an UpKeep native device or a custom device, the type name (e.g. "Vibration"), as well as some optional information about the make and model of the device. The device type also maps to certain device properties (deviceProperties). Device properties specify what a device measures, such as humidity, temperature, X-Axis vibration speed, etc.

Devices generate device readings (deviceReadings). Each device reading includes (i) the id of the device that generated the reading, (ii) the timestamp of the reading, (iii) the device property (i.e. what was measured), and (iv) the reading value. Device readings are grouped by timestamp to create time series datasets.

Devices can be associated with alerts. Alerts check device readings and trigger incidents anytime a device reading is over or under a specified threshold.

Device types

The device type specifies whether a device is an UpKeep native device or a custom device, the type name, as well as some optional information about the make and model of the device. A device type is also associated with device properties (more on device properties below).

The device type object

{
  "deviceTypeId": 1,
  "companyId": null,
  "createdAt": "2021-02-24 16:17:49.927239-08",
  "deviceProvider": "upkeep",
  "deviceTypeName": "UpKeep Vibration",
  "vendorDeviceTypeId": "95",
  "vendorName": "Monnit",
  "vendorModel": "Vibration Meter",
  "vendorSku": null,
  "deviceProperties": [
    {
      "devicePropertyId": 1,
      "createdAt": "2021-02-24T16:17:49.927239-08:00"
      "deviceTypeId": 1,
      "messageName": "xAxisSpeed",
      "propertyName": "X-Axis Speed",
      "unit": "mm/sec",
      "vendorPropertyId": "0",
    },
    {
      "devicePropertyId": 2,
      "createdAt": "2021-02-24T16:17:49.927239-08:00"
      "deviceTypeId": 1,
      "messageName": "yAxisSpeed",
      "propertyName": "Y-Axis Speed",
      "unit": "mm/sec",
      "vendorPropertyId": "1",
    }
  ]
}

Properties

Property	Type	Description
`deviceTypeId`	integer	Unique identifier for the device type.
`companyId`	integer	Unique identifier for the company associated with the device type.
`createdAt`	string	ISO 8601 timestamp. When the device type was created.
`deviceProvider`	string	Will be one of two values: `upkeep` for native UpKeep device types or `custom` for user created device types.
`deviceTypeName`	string	The name of the device type.
`vendorDeviceTypeId`	string	Optional. Vendor provided unique identifier for the device type.
`vendorName`	string	Optional. The device type maker.
`vendorModel`	string	Optional. The device type model.
`vendorSku`	string	Optional. The device type SKU.
`deviceProperties`	array of objects	An array of device properties associated with the device type. See below for more detail.

The device properties object

Device properties specify what a device measures, such as humidity, temperature, X-Axis vibration speed, etc. Device properties are always associated with a particular device type. Consider a vibration sensor that measures vibration speed along X, Y, and Z axes. That vibration sensor could have a device type of "Vibration" and device properties of "X-Axis Speed", "Y-Axis Speed", and "Z-Axis Speed".

{
  "devicePropertyId": 1,
  "createdAt": "2021-02-24T16:17:49.927239-08:00"
  "deviceTypeId": 1,
  "messageName": "xAxisSpeed",
  "propertyName": "X-Axis Speed",
  "unit": "mm/sec",
  "vendorPropertyId": "0",
}

Properties

Property	Type	Description
`devicePropertyId`	integer	Unique identifier for the device property.
`createdAt`	integer	ISO 8601 timestamp. When the device property was created.
`deviceTypeId`	integer	The device type with which the device property is associated.
`messageName`	string	The name for the device property as it appears in the device readings JSON payload sent to the Edge API.
`propertyName`	string	The human friendly name for the device property.
`unit`	string	The unit for the device property.
`vendorPropertyId`	string	Optional. Vendor provided unique identifier for the device type.

Create a device type

REQUEST

curl https://edge.onupkeep.com/api/v1/device-types \
-u YOUR_API_KEY: \
-X POST \
-H 'Content-Type: application/json' \
--data-raw '{
  "deviceTypeName": "Custom Vibration",
  "vendorDeviceTypeId": "83kn3k",
  "vendorModel": "XP-7",
  "vendorName": "Acme",
  "deviceProperties": [
    {
      "propertyName": "X-Axis Vibration",
      "messageName": "xAxisVib",
      "unit": "mm/sec"
    },
    {
      "propertyName": "Y-Axis Vibration",
      "messageName": "yAxisVib",
      "unit": "mm/sec"
    },
    {
      "propertyName": "Battery level",
      "messageName": "batteryLevel",
      "unit": "pct"
    },
    {
      "propertyName": "Signal strength",
      "messageName": "signalStrength",
      "unit": "pct"
    }
  ]
}'

RESPONSE

{
  "meta": {
    "dataFormat": "object"
  },
  "data": {
    "deviceTypeId": 4,
    "companyId": 1,
    "createdAt": "2021-02-26 14:49:32.984284-08",
    "deviceProvider": "custom",
    "deviceTypeName": "Custom Vibration",
    "vendorDeviceTypeId": "83kn3k",
    "vendorModel": "XP-7",
    "vendorName": "Acme",
    "vendorSku": null,
    "deviceProperties": [
      {
        "devicePropertyId": 15,
        "deviceTypeId": 4,
        "vendorPropertyId": null,
        "propertyName": "X-Axis Vibration",
        "messageName": "xAxisVib",
        "unit": "mm/sec",
        "createdAt": "2021-02-26 14:49:32.984284-08"
      },
      {
        "devicePropertyId": 16,
        "deviceTypeId": 4,
        "vendorPropertyId": null,
        "propertyName": "Y-Axis Vibration",
        "messageName": "yAxisVib",
        "unit": "mm/sec",
        "createdAt": "2021-02-26 14:49:32.984284-08"
      },
      {
        "devicePropertyId": 17,
        "deviceTypeId": 4,
        "vendorPropertyId": null,
        "propertyName": "Battery level",
        "messageName": "batteryLevel",
        "unit": "pct",
        "createdAt": "2021-02-26 14:49:32.984284-08"
      },
      {
        "devicePropertyId": 18,
        "deviceTypeId": 4,
        "vendorPropertyId": null,
        "propertyName": "Signal strength",
        "messageName": "signalStrength",
        "unit": "pct",
        "createdAt": "2021-02-26 14:49:32.984284-08"
      }
    ]
  }
}

HTTP Request

POST https://edge.onupkeep.com/api/v1/device-types

POST body parameters

Parameter	Type	Description
`deviceTypeName`	string	The name of the device type.
`vendorDeviceTypeId`	string	Optional. Vendor provided unique identifier for the device type.
`vendorName`	string	Optional. The device type maker.
`vendorModel`	string	Optional. The device type model.
`vendorSku`	string	Optional. The device type SKU.
`deviceProperties`	array of objects	An array of device properties associated with the device type. See below for more detail.

Device properties parameters

Parameter	Type	Description
`messageName`	string	The name for the device property as it appears in the device readings JSON payload sent to the Edge API.
`propertyName`	string	The human friendly name for the device property.
`unit`	string	The unit for the device property.
`vendorPropertyId`	string	Optional. Vendor provided unique identifier for the device type.

Get device types

REQUEST

curl https://edge.onupkeep.com/api/v1/device-types \
-u YOUR_API_KEY:

RESPONSE

{
  "meta": {
    "dataFormat": "array"
  },
  "data": [
    {
      "deviceTypeId": 5,
      "companyId": 1,
      "deviceProvider": "custom",
      "deviceTypeName": "Custom Vibration",
      "vendorDeviceTypeId": "83kn3k",
      "vendorName": "Acme",
      "vendorModel": "XP-7",
      "vendorSku": null,
      "createdAt": "2021-03-03 15:18:37.741569-08",
      "deviceProperties": [
        {
          "devicePropertyId": 22,
          "deviceTypeId": 5,
          "vendorPropertyId": null,
          "propertyName": "X-Axis Vibration",
          "messageName": "xAxisVib",
          "unit": "mm/sec",
          "createdAt": "2021-03-03T15:18:37.741569-08:00"
        },
        {
          "devicePropertyId": 23,
          "deviceTypeId": 5,
          "vendorPropertyId": null,
          "propertyName": "Y-Axis Vibration",
          "messageName": "yAxisVib",
          "unit": "mm/sec",
          "createdAt": "2021-03-03T15:18:37.741569-08:00"
        },
        {
          "devicePropertyId": 24,
          "deviceTypeId": 5,
          "vendorPropertyId": null,
          "propertyName": "Battery level",
          "messageName": "batteryLevel",
          "unit": "pct",
          "createdAt": "2021-03-03T15:18:37.741569-08:00"
        },
        {
          "devicePropertyId": 25,
          "deviceTypeId": 5,
          "vendorPropertyId": null,
          "propertyName": "Signal strength",
          "messageName": "signalStrength",
          "unit": "pct",
          "createdAt": "2021-03-03T15:18:37.741569-08:00"
        }
      ]
    }
  ]
}

HTTP Request

GET https://edge.onupkeep.com/api/v1/device-types

Query parameters

You can filter device types using the following (optional) query parameters:

Parameter	Type	Description
`deviceTypeName`	string	Optional. The name of the device type.
`vendorDeviceTypeId`	string	Optional. Vendor provided unique identifier for the device type.
`vendorName`	string	Optional. The device type maker.
`vendorModel`	string	Optional. The device type model.
`vendorSku`	string	Optional. The device type SKU.

Get a device type

REQUEST

curl https://edge.onupkeep.com/api/v1/device-types/5 \
-u YOUR_API_KEY:

RESPONSE

{
  "meta": {
    "dataFormat": "object"
  },
  "data": {
    "deviceTypeId": 5,
    "companyId": 1,
    "createdAt": "2021-03-03 15:18:37.741569-08",
    "deviceProvider": "custom",
    "deviceTypeName": "Custom Vibration",
    "vendorDeviceTypeId": "83kn3k",
    "vendorModel": "XP-7",
    "vendorName": "Acme",
    "vendorSku": null,
    "deviceProperties": [
      {
        "devicePropertyId": 22,
        "deviceTypeId": 5,
        "vendorPropertyId": null,
        "propertyName": "X-Axis Vibration",
        "messageName": "xAxisVib",
        "unit": "mm/sec",
        "createdAt": "2021-03-03T15:18:37.741569-08:00"
      },
      {
        "devicePropertyId": 23,
        "deviceTypeId": 5,
        "vendorPropertyId": null,
        "propertyName": "Y-Axis Vibration",
        "messageName": "yAxisVib",
        "unit": "mm/sec",
        "createdAt": "2021-03-03T15:18:37.741569-08:00"
      },
      {
        "devicePropertyId": 24,
        "deviceTypeId": 5,
        "vendorPropertyId": null,
        "propertyName": "Battery level",
        "messageName": "batteryLevel",
        "unit": "pct",
        "createdAt": "2021-03-03T15:18:37.741569-08:00"
      },
      {
        "devicePropertyId": 25,
        "deviceTypeId": 5,
        "vendorPropertyId": null,
        "propertyName": "Signal strength",
        "messageName": "signalStrength",
        "unit": "pct",
        "createdAt": "2021-03-03T15:18:37.741569-08:00"
      }
    ]
  }
}

HTTP Request

GET https://edge.onupkeep.com/api/v1/device-types/:deviceTypeId

URL parameter

Parameter	Type	Description
`deviceTypeId`	integer	Unique identifier for the device type.

Delete a device type

REQUEST

curl https://edge.onupkeep.com/api/v1/device-types/5 \
-u YOUR_API_KEY:
-X DELETE

RESPONSE

{
  "meta": {
    "dataFormat": "object"
  },
  "data": {
      "deviceTypeId": 5,
      "companyId": 1,
      "deviceProvider": "custom",
      "deviceTypeName": "Custom Vibration",
      "vendorDeviceTypeId": "83kn3k",
      "vendorName": "Acme",
      "vendorModel": "XP-7",
      "vendorSku": null,
      "createdAt": "2021-03-03 15:18:37.741569-08"
    }
  ]
}

HTTP Request

DELETE https://edge.onupkeep.com/api/v1/device-types/:deviceTypeId

URL parameter

Parameter	Type	Description
`deviceTypeId`	integer	Unique identifier for the device type.

Devices

Devices are the heart of the Edge platform. Devices are typically sensors, but they can also include gateways and anything else that regularly collects and transmits telemetry data.

The device object

{
  "meta": {
    "dataFormat": "object"
  },
  "data": {
    "deviceId": 6,
    "companyId": 1,
    "createdAt": "2021-03-04 15:56:40.93147-08",
    "deviceName": "Assembly line sensor #10",
    "deviceTypeId": 5,
    "heartbeat": null,
    "updatedAt": null,
    "upkeepCoreAssetId": "mxYOMsWAjO",
    "upkeepCoreAssetName": "HVAC",
    "upkeepCoreLocationId": "TK6PSOFrCu",
    "upkeepCoreLocationName": "7th floor",
    "vendorDeviceId": "531l2mkZ"
  }
}

Properties

Property	Type	Description
`deviceId`	integer	Unique identifier for the device.
`companyId`	integer	Unique identifier for the company associated with the device.
`createdAt`	string	ISO 8601 timestamp. When the device was created.
`deviceName`	string	The name of the device.
`deviceTypeId`	integer	Unique identifier for the device type with which the device is associated.
`heartbeat`	integer	Optional. The interval at which device will transmit readings.
`updatedAt`	string	ISO 8601 timestamp. When the device was updated.
`upkeepCoreAssetId`	string	Optional. Unique identifier for the asset associated with the device.
`upkeepCoreAssetName`	string	Optional. The name of the asset associated with the device.
`upkeepCoreLocationId`	string	Optional. Unique identifier for the location associated with the device.
`upkeepCoreLocationName`	string	Optional. The name of the location associated with the device.
`vendorDeviceId`	string	Vendor provided unique identifier for the device.

Create a device

REQUEST

curl https://edge.onupkeep.com/api/v1/devices \
-u YOUR_API_KEY: \
-X POST \
-H 'Content-Type: application/json' \
--data-raw '{
  "deviceTypeId": 5,
  "deviceName": "Assembly line sensor #10",
  "upkeepCoreAssetId": "mxYOMsWAjO",
  "upkeepCoreAssetName": "HVAC",
  "upkeepCoreLocationId": "TK6PSOFrCu",
  "upkeepCoreLocationName": "7th floor",
  "vendorDeviceId": "531l2mkZ"
}'

RESPONSE

{
  "meta": {
    "dataFormat": "object"
  },
  "data": {
    "deviceId": 6,
    "companyId": 1,
    "createdAt": "2021-03-04 15:56:40.93147-08",
    "deviceName": "Assembly line sensor #10",
    "deviceTypeId": 5,
    "heartbeat": null,
    "updatedAt": null,
    "upkeepCoreAssetId": "mxYOMsWAjO",
    "upkeepCoreAssetName": "HVAC",
    "upkeepCoreLocationId": "TK6PSOFrCu",
    "upkeepCoreLocationName": "7th floor",
    "vendorDeviceId": "531l2mkZ"
  }
}

Note that all devices have to be associated with a device type. This means if the appropriate device type does not exist, you'll need to create it prior to creating the device.

HTTP Request

POST https://edge.onupkeep.com/api/v1/devices

POST body parameters

Parameter	Type	Description
`deviceTypeId`	integer	Unique identifier for the device type associated with the device.
`deviceName`	string	The name of the device.
`heartbeat`	integer	Optional. The interval at which device will transmit readings.
`upkeepCoreAssetId`	string	Optional. Unique identifier for the asset associated with the device.
`upkeepCoreAssetName`	string	Optional. The name of the asset associated with the device.
`upkeepCoreLocationId`	string	Optional. Unique identifier for the location associated with the device.
`upkeepCoreLocationName`	string	Optional. The name of the location associated with the device.
`vendorDeviceId`	string	Vendor provided unique identifier for the device.

Get devices

REQUEST

curl https://edge.onupkeep.com/api/v1/devices \
-u YOUR_API_KEY:

RESPONSE

{
  "meta": {
    "dataFormat": "array"
  },
  "data": [
    {
      "deviceId": 1,
      "companyId": 1,
      "createdAt": "2021-03-03 15:18:37.754004-08",
      "deviceName": "Assembly line sensor #8",
      "deviceTypeId": 5,
      "heartbeat": null,
      "updatedAt": null,
      "upkeepCoreAssetId": "mxYOMsWAjO",
      "upkeepCoreAssetName": "HVAC",
      "upkeepCoreLocationId": "TK6PSOFrCu",
      "upkeepCoreLocationName": "7th floor",
      "vendorDeviceId": "3kkvelL23",
      "deviceType": {
        "deviceTypeId": 5,
        "deviceTypeName": "Custom Vibration",
        "deviceProvider": "custom",
        "vendorDeviceTypeId": "83kn3k",
        "vendorName": "Acme",
        "vendorModel": "XP-7",
        "vendorSku": null,
        "deviceProperties": [
          {
            "devicePropertyId": 22,
            "deviceTypeId": 5,
            "vendorPropertyId": null,
            "propertyName": "X-Axis Vibration",
            "messageName": "xAxisVib",
            "unit": "mm/sec",
            "createdAt": "2021-03-03T15:18:37.741569-08:00"
          },
          {
            "devicePropertyId": 23,
            "deviceTypeId": 5,
            "vendorPropertyId": null,
            "propertyName": "Y-Axis Vibration",
            "messageName": "yAxisVib",
            "unit": "mm/sec",
            "createdAt": "2021-03-03T15:18:37.741569-08:00"
          },
          {
            "devicePropertyId": 24,
            "deviceTypeId": 5,
            "vendorPropertyId": null,
            "propertyName": "Battery level",
            "messageName": "batteryLevel",
            "unit": "pct",
            "createdAt": "2021-03-03T15:18:37.741569-08:00"
          },
          {
            "devicePropertyId": 25,
            "deviceTypeId": 5,
            "vendorPropertyId": null,
            "propertyName": "Signal strength",
            "messageName": "signalStrength",
            "unit": "pct",
            "createdAt": "2021-03-03T15:18:37.741569-08:00"
          }
        ]
      },
      "alerts": null,
      "deviceReadings": [
        {
          "deviceReadingId": 1808,
          "messageId": 402,
          "readingValue": 56,
          "readingTimestamp": "2021-03-03T15:20:15.414-08:00",
          "devicePropertyId": 25,
          "deviceTypeId": 5,
          "vendorPropertyId": null,
          "propertyName": "Signal strength",
          "messageName": "signalStrength",
          "unit": "pct"
        },
        {
          "deviceReadingId": 1807,
          "messageId": 402,
          "readingValue": 85,
          "readingTimestamp": "2021-03-03T15:20:15.414-08:00",
          "devicePropertyId": 24,
          "deviceTypeId": 5,
          "vendorPropertyId": null,
          "propertyName": "Battery level",
          "messageName": "batteryLevel",
          "unit": "pct"
        },
        {
          "deviceReadingId": 1806,
          "messageId": 402,
          "readingValue": 22,
          "readingTimestamp": "2021-03-03T15:20:15.414-08:00",
          "devicePropertyId": 23,
          "deviceTypeId": 5,
          "vendorPropertyId": null,
          "propertyName": "Y-Axis Vibration",
          "messageName": "yAxisVib",
          "unit": "mm/sec"
        },
        {
          "deviceReadingId": 1805,
          "messageId": 402,
          "readingValue": 3,
          "readingTimestamp": "2021-03-03T15:20:15.414-08:00",
          "devicePropertyId": 22,
          "deviceTypeId": 5,
          "vendorPropertyId": null,
          "propertyName": "X-Axis Vibration",
          "messageName": "xAxisVib",
          "unit": "mm/sec"
        }
      ]
    }
  ]
}

HTTP Request

GET https://edge.onupkeep.com/api/v1/devices

Query parameters

You can filter devices using the following (optional) query parameters:

Parameter	Type	Description
`search`	string	Optional. Search term. If specified, all other query parameters will be ignored. Will search for approximate matches across `deviceName`, `deviceTypeName`, `vendorDeviceId`, asset name, and location name.
`deviceName`	string	Optional. The device name.
`deviceTypeId`	integer[]	Optional. Unique identifier for the device type associated with the device. More than one `deviceTypeId` may be passed. Use an array format when passing this parameter: `?deviceTypeId[]=5&deviceTypeId[]=6`. Passing this parameter without the array format will result in a `400` error.
`upkeepCoreAssetName`	string	Optional. The asset associated with the device.
`upkeepCoreLocationName`	string	Optional. The location associated with the device.
`vendorDeviceId`	string	Optional. Vendor provided unique identifier for the device.

For convenience, the GET /devices endpoint augments the device object with the following additional entities:

The full device type associated with each device.
Any alerts associated with each device.
The latest device readings for each device.

Get a device

REQUEST

curl https://edge.onupkeep.com/api/v1/devices/1 \
-u YOUR_API_KEY:

RESPONSE

{
  "meta": {
    "dataFormat": "object"
  },
  "data": {
    "deviceId": 1,
    "companyId": 1,
    "createdAt": "2021-03-03 15:18:37.754004-08",
    "deviceName": "Assembly line sensor #8",
    "deviceTypeId": 5,
    "heartbeat": null,
    "updatedAt": null,
    "upkeepCoreAssetId": "mxYOMsWAjO",
    "upkeepCoreAssetName": "HVAC",
    "upkeepCoreLocationId": "TK6PSOFrCu",
    "upkeepCoreLocationName": "7th floor",
    "vendorDeviceId": "3kkvelL23",
    "deviceType": {
      "deviceTypeId": 5,
      "deviceTypeName": "Custom Vibration",
      "deviceProvider": "custom",
      "vendorName": "Acme",
      "vendorModel": "XP-7",
      "deviceProperties": [
        {
          "devicePropertyId": 24,
          "propertyName": "Battery level",
          "messageName": "batteryLevel",
          "unit": "pct"
        },
        {
          "devicePropertyId": 25,
          "propertyName": "Signal strength",
          "messageName": "signalStrength",
          "unit": "pct"
        },
        {
          "devicePropertyId": 22,
          "propertyName": "X-Axis Vibration",
          "messageName": "xAxisVib",
          "unit": "mm/sec"
        },
        {
          "devicePropertyId": 23,
          "propertyName": "Y-Axis Vibration",
          "messageName": "yAxisVib",
          "unit": "mm/sec"
        }
      ]
    }
  }
}

HTTP Request

GET https://edge.onupkeep.com/api/v1/devices/:deviceId

URL parameter

Parameter	Type	Description
`deviceId`	string	Unique identifier for the device.

Update a device

REQUEST

curl https://edge.onupkeep.com/api/v1/devices/6 \
-u YOUR_API_KEY: \
-X POST \
-H 'Content-Type: application/json' \
--data-raw '{
  "deviceName": "Assembly line sensor #4"
}'

RESPONSE

{
  "meta": {
    "dataFormat": "object"
  },
  "data": {
    "deviceId": 6,
    "companyId": 1,
    "createdAt": "2021-03-04 15:56:40.93147-08",
    "deviceName": "Assembly line sensor #4",
    "deviceTypeId": 5,
    "heartbeat": null,
    "updatedAt": null,
    "upkeepCoreAssetId": "mxYOMsWAjO",
    "upkeepCoreAssetName": "HVAC",
    "upkeepCoreLocationId": "TK6PSOFrCu",
    "upkeepCoreLocationName": "7th floor",
    "vendorDeviceId": "531l2mkZ"
  }
}

HTTP Request

POST https://edge.onupkeep.com/api/v1/devices/:deviceId

POST body parameters

You must send the full set of alert parameters (the same parameters that are required when you first create a device).

You also cannot change an existing device's deviceType or vendorDeviceId with this endpoint. If you wish to change either of those properties, you will need to delete the device and then re-create it.

Parameter	Type	Description
`deviceName`	string	The name of the device.
`heartbeat`	integer	Optional. The interval at which device will transmit readings.
`upkeepCoreAssetId`	string	Optional. Unique identifier for the asset associated with the device.
`upkeepCoreAssetName`	string	Optional. The name of the asset associated with the device.
`upkeepCoreLocationId`	string	Optional. Unique identifier for the location associated with the device.
`upkeepCoreLocationName`	string	Optional. The name of the location associated with the device.

Delete a device

REQUEST

curl https://edge.onupkeep.com/api/v1/devices/6 \
-u YOUR_API_KEY: \
-X DELETE

RESPONSE

{
  "meta": {
    "dataFormat": "object"
  },
  "data": {
    "deviceId": 6,
    "companyId": 1,
    "createdAt": "2021-03-04 15:56:40.93147-08",
    "deviceName": "Assembly line sensor #4",
    "deviceTypeId": 5,
    "heartbeat": null,
    "updatedAt": null,
    "upkeepCoreAssetId": "mxYOMsWAjO",
    "upkeepCoreAssetName": "HVAC",
    "upkeepCoreLocationId": "TK6PSOFrCu",
    "upkeepCoreLocationName": "7th floor",
    "vendorDeviceId": "531l2mkZ"
  }
}

HTTP Request

DELETE https://edge.onupkeep.com/api/v1/devices/:deviceId

URL parameter

Parameter	Type	Description
`deviceId`	string	Unique identifier for the device.

Device readings

If you send data like this:

{
  "vendorDeviceId": "12345",
  "readingTimestamp": "2020-12-15T03:00:06.414Z",
  "xAxisVib": 17,
  "yAxisVib": 22
}

Edge will save the data like this:

{
  "meta": {
    "dataFormat": "array"
  },
  "data": [
    {
      "deviceReadings": [
        {
          "deviceReadingId": 1,
          "messageId": 1,
          "readingValue": 17,
          "readingTimestamp": "2020-12-15T03:00:06.414Z",
          "devicePropertyId": 8,
          "deviceTypeId": 1,
          "vendorPropertyId": "0",
          "propertyName": "X-Axis Vibration",
          "messageName": "xAxisVib",
          "unit": "mm/sec"
        },
        {
          "deviceReadingId": 2,
          "messageId": 1,
          "readingValue": 22,
          "readingTimestamp": "2020-12-15T03:00:06.414Z",
          "devicePropertyId": 9,
          "deviceTypeId": 1,
          "vendorPropertyId": "1",
          "propertyName": "Y-Axis Vibration",
          "messageName": "yAxisVib",
          "unit": "mm/sec"
        }
      ]
    }
  ]
}

Each device generates device readings. Edge uses a "narrow table model" for device readings, meaning each device property (e.g. X-Axis Speed) gets its own row in the database and its own object in the JSON payload. This allows Edge to be flexible and accommodate a wide variety of devices that measure many different properties.

Device readings are transmitted to the Edge API in a "wide table format" (i.e. all properties are included in a single object with a single timestamp), and this raw wide table transmission is saved as a message in the Edge database, before being converted to the narrow table format.

The device readings object

{
  "deviceReadings": [
    {
      "deviceReadingId": 1814,
      "devicePropertyId": 8,
      "deviceTypeId": 1,
      "messageId": 405,
      "messageName": "batteryLevel",
      "propertyName": "Battery level",
      "readingTimestamp": "2021-03-03T15:31:18-08:00",
      "readingValue": 91,
      "unit": "pct",
      "vendorPropertyId": null
    },
    {
      "deviceReadingId": 1815,
      "devicePropertyId": 9,
      "deviceTypeId": 1,
      "messageId": 405,
      "messageName": "signalStrength",
      "propertyName": "Signal strength",
      "readingTimestamp": "2021-03-03T15:31:18-08:00",
      "readingValue": 54,
      "unit": "pct",
      "vendorPropertyId": null
    },
    {
      "deviceReadingId": 1816,
      "devicePropertyId": 1,
      "deviceTypeId": 1,
      "messageId": 405,
      "messageName": "xAxisSpeed",
      "propertyName": "X-Axis Speed",
      "readingTimestamp": "2021-03-03T15:31:18-08:00",
      "readingValue": 5,
      "unit": "mm/sec",
      "vendorPropertyId": "0"
    },
    {
      "deviceReadingId": 1817,
      "devicePropertyId": 2,
      "deviceTypeId": 1,
      "messageId": 405,
      "messageName": "yAxisSpeed",
      "propertyName": "Y-Axis Speed",
      "readingTimestamp": "2021-03-03T15:31:18-08:00",
      "readingValue": 11,
      "unit": "mm/sec",
      "vendorPropertyId": "1"
    },
    {
      "deviceReadingId": 1818,
      "devicePropertyId": 3,
      "deviceTypeId": 1,
      "messageId": 405,
      "messageName": "zAxisSpeed",
      "propertyName": "Z-Axis Speed",
      "readingTimestamp": "2021-03-03T15:31:18-08:00",
      "readingValue": 18,
      "unit": "mm/sec",
      "vendorPropertyId": "2"
    },
    {
      "deviceReadingId": 1819,
      "devicePropertyId": 4,
      "deviceTypeId": 1,
      "messageId": 405,
      "messageName": "xAxisFrequency",
      "propertyName": "X-Axis Frequency",
      "readingTimestamp": "2021-03-03T15:31:18-08:00",
      "readingValue": 85,
      "unit": "Hz",
      "vendorPropertyId": "3"
    },
    {
      "deviceReadingId": 1820,
      "devicePropertyId": 5,
      "deviceTypeId": 1,
      "messageId": 405,
      "messageName": "yAxisFrequency",
      "propertyName": "Y-Axis Frequency",
      "readingTimestamp": "2021-03-03T15:31:18-08:00",
      "readingValue": 71,
      "unit": "Hz",
      "vendorPropertyId": "4"
    },
    {
      "deviceReadingId": 1821,
      "devicePropertyId": 6,
      "deviceTypeId": 1,
      "messageId": 405,
      "messageName": "zAxisFrequency",
      "propertyName": "Z-Axis Frequency",
      "readingTimestamp": "2021-03-03T15:31:18-08:00",
      "readingValue": 67,
      "unit": "Hz",
      "vendorPropertyId": "5"
    },
    {
      "deviceReadingId": 1822,
      "devicePropertyId": 7,
      "deviceTypeId": 1,
      "messageId": 405,
      "messageName": "dutyCycle",
      "propertyName": "Duty Cycle",
      "readingTimestamp": "2021-03-03T15:31:18-08:00",
      "readingValue": 97,
      "unit": "pct",
      "vendorPropertyId": "6"
    }
  ]
}

Properties

Device readings are grouped into an array by timestamp under a deviceReadings property. Each device reading has the following properties:

Property	Type	Description
`deviceReadingId`	integer	Unique identifier for the device reading.
`devicePropertyId`	integer	Unique identifier for the device property associated with the reading.
`deviceTypeId`	integer	Unique identifier for the device type associated with the reading.
`messageId`	integer	Unique identifier for the message associated with the reading.
`messageName`	string	The property name in a JSON-friendly format.
`propertyName`	string	The property name (e.g. "X-Axis Vibration").
`readingTimestamp`	string	ISO 8601 timestamp. When the reading was generated.
`readingValue`	number	The reading value.
`unit`	string	The units for the reading value.
`vendorPropertyId`	string	Optional. Vendor provided unique identifier for the device property.

Create a device reading

REQUEST

curl https://edge.onupkeep.com/api/v1/device-readings \
-u YOUR_API_KEY: \
-X POST \
-H 'Content-Type: application/json' \
--data-raw '{
  "vendorDeviceId": "3kkvelL23",
  "readingTimestamp": "2021-03-09T19:50:06.414Z",
  "xAxisVib": 14,
  "yAxisVib": 25,
  "batteryLevel": 75,
  "signalStrength": 32
}'

RESPONSE

{
  "meta": {
    "dataFormat": "object"
  },
  "data": {
    "deviceId": 1,
    "messageId": 412,
    "messageTimestamp": "2021-03-09 11:50:06.414-08",
    "vendorMessageId": null,
    "deviceReadings": [
      {
        "deviceReadingId": 1838,
        "messageId": 412,
        "readingValue": 14,
        "readingTimestamp": "2021-03-09T11:50:06.414-08:00",
        "devicePropertyId": 22,
        "deviceTypeId": 5,
        "vendorPropertyId": null,
        "propertyName": "X-Axis Vibration",
        "messageName": "xAxisVib",
        "unit": "mm/sec"
      },
      {
        "deviceReadingId": 1839,
        "messageId": 412,
        "readingValue": 25,
        "readingTimestamp": "2021-03-09T11:50:06.414-08:00",
        "devicePropertyId": 23,
        "deviceTypeId": 5,
        "vendorPropertyId": null,
        "propertyName": "Y-Axis Vibration",
        "messageName": "yAxisVib",
        "unit": "mm/sec"
      },
      {
        "deviceReadingId": 1840,
        "messageId": 412,
        "readingValue": 75,
        "readingTimestamp": "2021-03-09T11:50:06.414-08:00",
        "devicePropertyId": 24,
        "deviceTypeId": 5,
        "vendorPropertyId": null,
        "propertyName": "Battery level",
        "messageName": "batteryLevel",
        "unit": "pct"
      },
      {
        "deviceReadingId": 1841,
        "messageId": 412,
        "readingValue": 32,
        "readingTimestamp": "2021-03-09T11:50:06.414-08:00",
        "devicePropertyId": 25,
        "deviceTypeId": 5,
        "vendorPropertyId": null,
        "propertyName": "Signal strength",
        "messageName": "signalStrength",
        "unit": "pct"
      }
    ]
  }
}

HTTP Request

POST https://edge.onupkeep.com/api/v1/device-readings

POST body parameters

Parameter	Type	Description
`vendorDeviceId`	string	Vendor provided unique identifier for the device.
`readingTimestamp`	string	ISO 8601 timestamp. When the reading was generated.
`[readingValues]`	key: value pairs	Add your readings in key: value pairs, with each key corresponding to the `messageName` you specified when creating the individual device property, and each value being the actual reading value.

Get device readings

REQUEST

curl https://edge.onupkeep.com/api/v1/devices-readings/5 \
-u YOUR_API_KEY: \
-d startDate=2021-03-01T22:18:39-08:00
-d endDate=2021-03-03T15:31:18-08:00
-G

RESPONSE

{
  "meta": {
    "dataFormat": "array"
  },
  "data": [
    {
      "deviceReadings": [
        {
          "deviceReadingId": 1814,
          "devicePropertyId": 8,
          "deviceTypeId": 1,
          "messageId": 405,
          "messageName": "batteryLevel",
          "propertyName": "Battery level",
          "readingTimestamp": "2021-03-03T15:31:18-08:00",
          "readingValue": 91,
          "unit": "pct",
          "vendorPropertyId": null
        },
        {
          "deviceReadingId": 1815,
          "devicePropertyId": 9,
          "deviceTypeId": 1,
          "messageId": 405,
          "messageName": "signalStrength",
          "propertyName": "Signal strength",
          "readingTimestamp": "2021-03-03T15:31:18-08:00",
          "readingValue": 54,
          "unit": "pct",
          "vendorPropertyId": null
        },
        {
          "deviceReadingId": 1816,
          "devicePropertyId": 1,
          "deviceTypeId": 1,
          "messageId": 405,
          "messageName": "xAxisSpeed",
          "propertyName": "X-Axis Speed",
          "readingTimestamp": "2021-03-03T15:31:18-08:00",
          "readingValue": 5,
          "unit": "mm/sec",
          "vendorPropertyId": "0"
        },
        {
          "deviceReadingId": 1817,
          "devicePropertyId": 2,
          "deviceTypeId": 1,
          "messageId": 405,
          "messageName": "yAxisSpeed",
          "propertyName": "Y-Axis Speed",
          "readingTimestamp": "2021-03-03T15:31:18-08:00",
          "readingValue": 11,
          "unit": "mm/sec",
          "vendorPropertyId": "1"
        },
        {
          "deviceReadingId": 1818,
          "devicePropertyId": 3,
          "deviceTypeId": 1,
          "messageId": 405,
          "messageName": "zAxisSpeed",
          "propertyName": "Z-Axis Speed",
          "readingTimestamp": "2021-03-03T15:31:18-08:00",
          "readingValue": 18,
          "unit": "mm/sec",
          "vendorPropertyId": "2"
        },
        {
          "deviceReadingId": 1819,
          "devicePropertyId": 4,
          "deviceTypeId": 1,
          "messageId": 405,
          "messageName": "xAxisFrequency",
          "propertyName": "X-Axis Frequency",
          "readingTimestamp": "2021-03-03T15:31:18-08:00",
          "readingValue": 85,
          "unit": "Hz",
          "vendorPropertyId": "3"
        },
        {
          "deviceReadingId": 1820,
          "devicePropertyId": 5,
          "deviceTypeId": 1,
          "messageId": 405,
          "messageName": "yAxisFrequency",
          "propertyName": "Y-Axis Frequency",
          "readingTimestamp": "2021-03-03T15:31:18-08:00",
          "readingValue": 71,
          "unit": "Hz",
          "vendorPropertyId": "4"
        },
        {
          "deviceReadingId": 1821,
          "devicePropertyId": 6,
          "deviceTypeId": 1,
          "messageId": 405,
          "messageName": "zAxisFrequency",
          "propertyName": "Z-Axis Frequency",
          "readingTimestamp": "2021-03-03T15:31:18-08:00",
          "readingValue": 67,
          "unit": "Hz",
          "vendorPropertyId": "5"
        },
        {
          "deviceReadingId": 1822,
          "devicePropertyId": 7,
          "deviceTypeId": 1,
          "messageId": 405,
          "messageName": "dutyCycle",
          "propertyName": "Duty Cycle",
          "readingTimestamp": "2021-03-03T15:31:18-08:00",
          "readingValue": 97,
          "unit": "pct",
          "vendorPropertyId": "6"
        }
      ]
    }
  ]
}

HTTP Request

GET https://edge.onupkeep.com/api/v1/device-readings/:deviceId

URL & Query parameters

Note that you must provide a date range (startDate and endDate parameters) as query parameters.

Parameter	Type	Description
`deviceId`	string	Url parameter. Unique identifier for the device.
`startDate`	string	ISO 8601 timestamp. Start date for the readings.
`endDate`	string	ISO 8601 timestamp. End date for the readings.

Alerts

Alerts are used to highlight when device readings exceed or fall below a certain threshold. Once you set an alert for a particular device, any time Edge detects an out of range reading, Edge will send the appropriate email and/or text notifications and also create an incident to track how long a particular device spends out of range.

The alert object

{
  "alertId": 2,
  "active": true,
  "alertName": "High vibration alert",
  "companyId": 1,
  "createdAt": "2021-03-09 15:44:39.974498-08",
  "deviceTypeId": 5,
  "duration": 30,
  "updatedAt": null,
  "alertProperties": [
    {
      "alertPropertyId": 2,
      "devicePropertyId": 22,
      "deviceTypeId": 5,
      "messageName": "xAxisVib",
      "operator": "gt",
      "propertyName": "X-Axis Vibration",
      "threshold": 20,
      "unit": "mm/sec"
      "vendorPropertyId": null,
    }
  ],
  "alertDevices": [
    {
      "deviceId": 1,
      "deviceName": "Assembly line sensor #8",
      "vendorDeviceId": "3kkvelL23",
      "heartbeat": null,
      "deviceTypeId": 5,
      "upkeepCoreAssetId": "mxYOMsWAjO",
      "upkeepCoreAssetName": "HVAC",
      "upkeepCoreLocationId": "TK6PSOFrCu",
      "upkeepCoreLocationName": "7th floor"
    }
  ],
  "alertRecipients": [
    {
      "alertRecipientId": 2,
      "email": "[email protected]",
      "phoneNumber": "+13159038571"
    }
  ]
}

Properties

Property	Type	Description
`alertId`	integer	Unique identifier for the alert.
`active`	boolean	Whether the alert is on or off.
`alertName`	string	The alert name.
`companyId`	integer	Unique identifer for the company associated with the alert.
`createdAt`	string	ISO 8601 timestamp. When the alert was created.
`deviceTypeId`	integer	Unique identifer for the device type with which the alert is associated.
`duration`	integer	The amount of time, in minutes, Edge should wait before triggering an alert when readings are out of range.
`updatedAt`	string	ISO 8601 timestamp. When the alert was updated.
`alertProperties`	array of objects	An array of the properties to check. See the `alertProperties` object below.
`alertDevices`	array of objects	An array of the devices associated with the alert.
`alertRecipients`	array of objects	Optional. An array of recipients to be notified when an alert is triggered.

Alert properties

The objects in the alert properties array include all the usual deviceProperties plus the following:

Property	Type	Description
`alertPropertyId`	integer	Unique identifier for the alert property.
`operator`	string	Can be `gt` (greater than) or `lt` (less than).
`threshold`	number	The threshold above or below which will trigger an alert.

Devices with more than one device property can have more than one alert property.

Create an alert

REQUEST

curl https://edge.onupkeep.com/api/v1/alerts \
-u YOUR_API_KEY: \
-X POST \
-H 'Content-Type: application/json' \
--data-raw '{
  "alertName": "High vibration alert",
  "deviceTypeId": 5,
  "alertDevices": [
    {
      "deviceId": 1
    }
  ],
  "alertProperties": [
    {
      "devicePropertyId": 22,
      "threshold": 20,
      "operator": "gt"
    }
  ],
  "alertRecipients": [
    {
      "email": "[email protected]",
      "phoneNumber": "+13159038571"
    }
  ],
  "duration": 30
}'

RESPONSE

{
  "meta": {
    "dataFormat": "object"
  },
  "data": {
    "alertId": 2,
    "active": true,
    "alertName": "High vibration alert",
    "companyId": 1,
    "createdAt": "2021-03-09 15:44:39.974498-08",
    "deviceTypeId": 5,
    "duration": 30,
    "updatedAt": null,
    "alertProperties": [
      {
        "alertPropertyId": 2,
        "threshold": 20,
        "operator": "gt",
        "devicePropertyId": 22,
        "deviceTypeId": 5,
        "vendorPropertyId": null,
        "propertyName": "X-Axis Vibration",
        "messageName": "xAxisVib",
        "unit": "mm/sec"
      }
    ],
    "alertDevices": [
      {
        "deviceId": 1,
        "deviceName": "Assembly line sensor #8",
        "vendorDeviceId": "3kkvelL23",
        "heartbeat": null,
        "deviceTypeId": 5,
        "upkeepCoreAssetId": "mxYOMsWAjO",
        "upkeepCoreAssetName": "HVAC",
        "upkeepCoreLocationId": "TK6PSOFrCu",
        "upkeepCoreLocationName": "7th floor"
      }
    ],
    "alertRecipients": [
      {
        "alertRecipientId": 2,
        "email": "[email protected]",
        "phoneNumber": "+13159038571"
      }
    ]
  }
}

HTTP Request

POST https://edge.onupkeep.com/api/v1/alerts

POST body parameters

Parameter	Type	Description
`alertName`	string	The alert name.
`deviceTypeId`	integer	Unique identifer for the device type with which the alert is associated.
`duration`	integer	The amount of time, in minutes, Edge should wait before triggering an alert when readings are out of range.
`alertProperties`	array of objects	An array of the properties to check. See the `alertProperties` object below.
`alertDevices`	array of objects	An array of the devices associated with the alert.
`alertRecipients`	array of objects	Optional. An array of recipients to be notified when an alert is triggered.

Alert properties

The objects in the alert properties array include all the usual deviceProperties plus the following:

Parameter	Type	Description
`alertPropertyId`	integer	Unique identifier for the alert property.
`operator`	string	Can be `gt` (greater than) or `lt` (less than).
`threshold`	number	The threshold above or below which will trigger an alert.

Get alerts

REQUEST

curl https://edge.onupkeep.com/api/v1/alerts \
-u YOUR_API_KEY:

RESPONSE

{
  "meta": {
    "dataFormat": "array"
  },
  "data": [
    {
      "alertId": 2,
      "companyId": 1,
      "deviceTypeId": 5,
      "alertName": "High vibration alert",
      "active": true,
      "duration": 30,
      "oldAlertId": null,
      "createdAt": "2021-03-09 15:44:39.974498-08",
      "updatedAt": null,
      "alertProperties": [
        {
          "alertPropertyId": 2,
          "threshold": 20,
          "operator": "gt",
          "devicePropertyId": 22,
          "deviceTypeId": 5,
          "vendorPropertyId": null,
          "propertyName": "X-Axis Vibration",
          "messageName": "xAxisVib",
          "unit": "mm/sec"
        }
      ],
      "alertDevices": [
        {
          "deviceId": 1,
          "deviceName": "Assembly line sensor #8",
          "vendorDeviceId": "3kkvelL23",
          "heartbeat": null,
          "deviceTypeId": 5,
          "deviceTypeName": "Custom Vibration",
          "upkeepCoreAssetId": "mxYOMsWAjO",
          "upkeepCoreAssetName": "HVAC",
          "upkeepCoreLocationId": "TK6PSOFrCu",
          "upkeepCoreLocationName": "7th floor"
        }
      ],
      "alertRecipients": [
        {
          "alertRecipientId": 2,
          "email": "[email protected]",
          "phoneNumber": "+13159038571"
        }
      ]
    }
  ]
}

HTTP Request

GET https://edge.onupkeep.com/api/v1/alerts

Query parameters

There are no query parameters for this endpoint.

Get an alert

REQUEST

curl https://edge.onupkeep.com/api/v1/alerts/2 \
-u YOUR_API_KEY:

RESPONSE

{
  "meta": {
    "dataFormat": "object"
  },
  "data": {
    "alertId": 2,
    "companyId": 1,
    "deviceTypeId": 5,
    "alertName": "High vibration alert",
    "active": true,
    "duration": 30,
    "oldAlertId": null,
    "createdAt": "2021-03-09 15:44:39.974498-08",
    "updatedAt": null,
    "alertProperties": [
      {
        "alertPropertyId": 2,
        "threshold": 20,
        "operator": "gt",
        "devicePropertyId": 22,
        "deviceTypeId": 5,
        "vendorPropertyId": null,
        "propertyName": "X-Axis Vibration",
        "messageName": "xAxisVib",
        "unit": "mm/sec"
      }
    ],
    "alertDevices": [
      {
        "deviceId": 1,
        "deviceName": "Assembly line sensor #8",
        "vendorDeviceId": "3kkvelL23",
        "heartbeat": null,
        "deviceTypeId": 5,
        "upkeepCoreAssetId": "mxYOMsWAjO",
        "upkeepCoreAssetName": "HVAC",
        "upkeepCoreLocationId": "TK6PSOFrCu",
        "upkeepCoreLocationName": "7th floor"
      }
    ],
    "alertRecipients": [
      {
        "alertRecipientId": 2,
        "email": "[email protected]",
        "phoneNumber": "+13159038571"
      }
    ]
  }
}

HTTP Request

GET https://edge.onupkeep.com/api/v1/alerts/:alertId

URL parameter

Parameter	Type	Description
`alertId`	integer	Unique identifier for the alert.

Toggle an alert

REQUEST

curl https://edge.onupkeep.com/api/v1/alerts/2 \
-u YOUR_API_KEY: \
-X POST \
-H 'Content-Type: application/json' \
--data-raw '{
  "active": false
}'

RESPONSE

{
  "meta": {
    "dataFormat": "object"
  },
  "data": {
    "alertId": 2,
    "companyId": 1,
    "deviceTypeId": 5,
    "alertName": "High vibration alert",
    "active": false,
    "duration": 30,
    "oldAlertId": null,
    "createdAt": "2021-03-09 15:44:39.974498-08",
    "updatedAt": "2021-03-09 17:20:38.593743-08",
    "alertProperties": [
      {
        "alertPropertyId": 2,
        "threshold": 20,
        "operator": "gt",
        "devicePropertyId": 22,
        "deviceTypeId": 5,
        "vendorPropertyId": null,
        "propertyName": "X-Axis Vibration",
        "messageName": "xAxisVib",
        "unit": "mm/sec"
      }
    ],
    "alertDevices": [
      {
        "deviceId": 1,
        "deviceName": "Assembly line sensor #8",
        "vendorDeviceId": "3kkvelL23",
        "heartbeat": null,
        "deviceTypeId": 5,
        "upkeepCoreAssetId": "mxYOMsWAjO",
        "upkeepCoreAssetName": "HVAC",
        "upkeepCoreLocationId": "TK6PSOFrCu",
        "upkeepCoreLocationName": "7th floor"
      }
    ],
    "alertRecipients": [
      {
        "alertRecipientId": 2,
        "email": "[email protected]",
        "phoneNumber": "+13159038571"
      }
    ]
  }
}

HTTP Request

POST https://edge.onupkeep.com/api/v1/alerts/:alertId/toggle

URL parameter

Parameter	Type	Description
`alertId`	integer	Unique identifier for the alert.

Post body parameter

Parameter	Type	Description
`active`	integer	Unique identifier for the alert.

Update an alert

REQUEST

curl https://edge.onupkeep.com/api/v1/alerts/2 \
-u YOUR_API_KEY: \
-X POST \
-H 'Content-Type: application/json' \
--data-raw '{
  "alertName": "Low vibration alert",
  "deviceTypeId": 5,
  "alertDevices": [
    {
      "deviceId": 1
    }
  ],
  "alertProperties": [
    {
      "devicePropertyId": 22,
      "threshold": 5,
      "operator": "lt"
    }
  ],
  "alertRecipients": [
    {
      "email": "[email protected]",
      "phoneNumber": "+13159038571"
    }
  ],
  "duration": 30
}'

RESPONSE

{
  "meta": {
    "dataFormat": "object"
  },
  "data": {
    "alertId": 2,
    "companyId": 1,
    "deviceTypeId": 5,
    "alertName": "Low vibration alert",
    "active": false,
    "duration": 30,
    "oldAlertId": null,
    "createdAt": "2021-03-09 15:44:39.974498-08",
    "updatedAt": "2021-03-09 17:40:56.327501-08",
    "alertProperties": [
      {
        "alertPropertyId": 3,
        "threshold": 5,
        "operator": "lt",
        "devicePropertyId": 22,
        "deviceTypeId": 5,
        "vendorPropertyId": null,
        "propertyName": "X-Axis Vibration",
        "messageName": "xAxisVib",
        "unit": "mm/sec"
      }
    ],
    "alertDevices": [
      {
        "deviceId": 1,
        "deviceName": "Assembly line sensor #8",
        "vendorDeviceId": "3kkvelL23",
        "heartbeat": null,
        "deviceTypeId": 5,
        "upkeepCoreAssetId": "mxYOMsWAjO",
        "upkeepCoreAssetName": "HVAC",
        "upkeepCoreLocationId": "TK6PSOFrCu",
        "upkeepCoreLocationName": "7th floor"
      }
    ],
    "alertRecipients": [
      {
        "alertRecipientId": 3,
        "email": "[email protected]",
        "phoneNumber": "+13159038571"
      }
    ]
  }
}

HTTP Request

POST https://edge.onupkeep.com/api/v1/alerts/:alertId

POST body parameters

You must send the full set of alert parameters (the same parameters that are required when you first create an alert).

Parameter	Type	Description
`alertName`	string	The alert name.
`deviceTypeId`	integer	Unique identifer for the device type with which the alert is associated.
`duration`	integer	The amount of time, in minutes, Edge should wait before triggering an alert when readings are out of range.
`alertProperties`	array of objects	An array of the properties to check. See the `alertProperties` object below.
`alertDevices`	array of objects	An array of the devices associated with the alert.
`alertRecipients`	array of objects	Optional. An array of recipients to be notified when an alert is triggered.

Alert properties

The objects in the alert properties array include all the usual deviceProperties plus the following:

Parameter	Type	Description
`alertPropertyId`	integer	Unique identifier for the alert property.
`operator`	string	Can be `gt` (greater than) or `lt` (less than).
`threshold`	number	The threshold above or below which will trigger an alert.

Delete an alert

REQUEST

curl https://edge.onupkeep.com/api/v1/alerts/2 \
-u YOUR_API_KEY:
-X DELETE

RESPONSE

{
  "meta": {
    "dataFormat": "object"
  },
  "data": {
    "alertId": 2,
    "companyId": 1,
    "deviceTypeId": 5,
    "alertName": "Low vibration alert",
    "active": false,
    "duration": 30,
    "oldAlertId": null,
    "createdAt": "2021-03-09 15:44:39.974498-08",
    "updatedAt": "2021-03-09 17:40:56.327501-08"
  }
}

HTTP Request

DELETE https://edge.onupkeep.com/api/v1/alerts/:alertId

URL parameter

Parameter	Type	Description
`alertId`	integer	Unique identifier for the alert.

Incidents

Incidents are created whenever an alert is triggered. For example, if you set an alert on a temperature device for 75 °F, and the device emits a reading of 78 °F, Edge will create an "active" incident. Subsequent out or range readings will be added to the incident. Once an in range reading is detected, the incident will be marked as "resolved".

The incidents object

{
  "incidentId": 1,
  "alertId": 1,
  "alertName": "Primary alert",
  "companyId": 1,
  "createdAt": "2021-03-10 17:58:16.4001-08",
  "deviceId": 1,
  "deviceName": "Assembly line sensor #8",
  "incidentStatus": "active",
  "resolvedAt": null,
  "upkeepCoreAssetId": "mxYOMsWAjO",
  "upkeepCoreAssetName": "HVAC",
  "upkeepCoreLocationId": "TK6PSOFrCu",
  "upkeepCoreLocationName": "7th floor",
  "incidentMessages": [
    {
      "messageId": 400001,
      "incidentStatusAtMessage": "active",
      "deviceId": 1,
      "deviceName": "Assembly line sensor #8",
      "vendorMessageId": null,
      "messageTimestamp": "2021-03-10T17:55:06.414-08:00"
    }
  ]
}

Properties

Property	Type	Description
`incidentId`	integer	Unique identifier for the incident.
`alertId`	integer	Unique identifier for the alert associated with incident.
`alertName`	string	The alert associated with the incident.
`companyId`	integer	Unique identifier for the company associated with the incident.
`createdAt`	string	ISO 8601 timestamp. When the incident was created.
`deviceId`	integer	Unique identifier for the device associated with the incident.
`deviceName`	string	Name of the device associated with the incident.
`incidentStatus`	string	Will be "active" for active incidents and "resolved" for resolved incidents.
`resolvedAt`	string	ISO 8601 timestamp. When the incident was resolved.
`upkeepCoreAssetId`	string	Optional. Unique identifier for the asset associated with the device.
`upkeepCoreAssetName`	string	Optional. The name of the asset associated with the device.
`upkeepCoreLocationId`	string	Optional. Unique identifier for the location associated with the device.
`upkeepCoreLocationName`	string	Optional. The name of the location associated with the device.
`incidentMessages`	array of objects	An array of device messages (which point to readings) associated with the incident.

Get incidents

REQUEST

curl https://edge.onupkeep.com/api/v1/incidents \
-u YOUR_API_KEY: \
-d startDate=2021-03-11T01:50:06Z
-d endDate=2021-03-11T01:59:06Z
-G

RESPONSE

{
  "meta": {
    "dataFormat": "array"
  },
  "data": [
    {
      "incidentId": 1,
      "alertId": 1,
      "alertName": "Primary alert",
      "companyId": 1,
      "createdAt": "2021-03-10 17:58:16.4001-08",
      "deviceId": 1,
      "deviceName": "Assembly line sensor #8",
      "incidentStatus": "active",
      "oldIncidentId": null,
      "resolvedAt": null,
      "upkeepCoreAssetId": "mxYOMsWAjO",
      "upkeepCoreAssetName": "HVAC",
      "upkeepCoreLocationId": "TK6PSOFrCu",
      "upkeepCoreLocationName": "7th floor",
      "incidentMessages": [
        {
          "messageId": 400001,
          "incidentStatusAtMessage": "active",
          "deviceId": 1,
          "deviceName": "Assembly line sensor #8",
          "vendorMessageId": null,
          "messageTimestamp": "2021-03-10T17:55:06.414-08:00"
        }
      ]
    }
  ]
}

HTTP Request

GET https://edge.onupkeep.com/api/v1/incidents

Query parameters

Note that you must provide a date range (startDate and endDate parameters) as query parameters.

Parameter	Type	Description
`startDate`	string	ISO 8601 timestamp. Start date for the readings.
`endDate`	string	ISO 8601 timestamp. End date for the readings.
`search`	string	Optional. Search incidents by incident status, alert name, or device name.

Get an incident

REQUEST

curl https://edge.onupkeep.com/api/v1/incidents/1 \
-u YOUR_API_KEY:

RESPONSE

{
  "meta": {
    "dataFormat": "object"
  },
  "data": {
    "incidentId": 1,
    "alertId": 1,
    "alertName": "Primary alert",
    "companyId": 1,
    "createdAt": "2021-03-10 17:58:16.4001-08",
    "deviceId": 1,
    "deviceName": "Assembly line sensor #8",
    "incidentStatus": "active",
    "resolvedAt": null,
    "upkeepCoreAssetId": "mxYOMsWAjO",
    "upkeepCoreAssetName": "HVAC",
    "upkeepCoreLocationId": "TK6PSOFrCu",
    "upkeepCoreLocationName": "7th floor",
    "incidentMessages": [
      {
        "messageId": 400001,
        "incidentStatusAtMessage": "active",
        "deviceId": 1,
        "deviceName": "Assembly line sensor #8",
        "vendorMessageId": null,
        "messageTimestamp": "2021-03-10T17:55:06.414-08:00",
        "deviceReadings": [
          {
            "deviceReadingId": 1800001,
            "messageId": 400001,
            "readingValue": 55,
            "readingTimestamp": "2021-03-10T17:55:06.414-08:00",
            "devicePropertyId": 22,
            "deviceTypeId": 5,
            "vendorPropertyId": null,
            "propertyName": "X-Axis Vibration",
            "messageName": "xAxisVib",
            "unit": "mm/sec"
          },
          {
            "deviceReadingId": 1800002,
            "messageId": 400001,
            "readingValue": 13,
            "readingTimestamp": "2021-03-10T17:55:06.414-08:00",
            "devicePropertyId": 23,
            "deviceTypeId": 5,
            "vendorPropertyId": null,
            "propertyName": "Y-Axis Vibration",
            "messageName": "yAxisVib",
            "unit": "mm/sec"
          },
          {
            "deviceReadingId": 1800003,
            "messageId": 400001,
            "readingValue": 75,
            "readingTimestamp": "2021-03-10T17:55:06.414-08:00",
            "devicePropertyId": 24,
            "deviceTypeId": 5,
            "vendorPropertyId": null,
            "propertyName": "Battery level",
            "messageName": "batteryLevel",
            "unit": "pct"
          },
          {
            "deviceReadingId": 1800004,
            "messageId": 400001,
            "readingValue": 32,
            "readingTimestamp": "2021-03-10T17:55:06.414-08:00",
            "devicePropertyId": 25,
            "deviceTypeId": 5,
            "vendorPropertyId": null,
            "propertyName": "Signal strength",
            "messageName": "signalStrength",
            "unit": "pct"
          }
        ]
      }
    ]
  }
}

HTTP Request

GET https://edge.onupkeep.com/api/v1/incidents/:incidentId

Note that the response for a single incident provides all device readings associated with each incident message.

URL parameter

Parameter	Type	Description
`incidentId`	integer	Unique identifier for the incident.

Respond to an incident

REQUEST

curl https://edge.onupkeep.com/api/v1/incidents/1/respond \
-u YOUR_API_KEY: \
-X POST \
-H 'Content-Type: application/json' \
--data-raw '{
  "action": "work-orders",
}'

RESPONSE (will include work-order or request data as appropriate)

{
  "meta": {
    "dataFormat": "object"
  },
  "data": {
    "id": "6yDTWLAEmh",
    "workOrderNo": "006",
    "title": "Device Ana Prod North Gate is out of range",
    "description": "Alert: Ana Prod Alert",
    "status": "open",
    "dueDate": "2021-03-09T07:20:22.310Z",
    "asset": "knyWfDnXWo",
    "location": "cXRAu708NU",
    "createdAt": "2021-03-09T07:56:53.743Z",
    "updatedAt": null
  }
}

You can create a work order or request in response to a specific incident.

HTTP Request

POST https://edge.onupkeep.com/api/v1/incidents/:incidentId/respond

POST body parameters

Parameter	Type	Description
`action`	string	The action to perform in response to the incident. Can either be "work-orders" or "requests".