Everactive
API docs by Redocly

Everactive API v2020-07 (v2020-07)

Download OpenAPI specification:

Everactive: success@everactive.com URL: https://everactive.com

Public API to interact with Everactive.

Overview

The Everactive API consists of two modules: a RESTful API for querying and updating data, and webhooks for consuming events related to your equipment.

REST API

The Everactive REST API allows you to perform queries and updates for your equipment monitored by Everactive.

To use the Everactive API you must obtain authorization client credentials. At this time, authorization client credentials are available to Everactive partners and can be obtained by contacting Everactive.

The credentials consist of a client ID and client secret combination. The client ID/client secret combination is only intended for server-side integrations with the Everactive API. The client secret must be protected and hidden from end users. It is the responsibility of developers integrating their backend systems with Everactive to keep the client secret secure.

Authentication

The Everactive REST API uses OAuth2 (https://tools.ietf.org/html/rfc6749) and the client_credentials flow to authenticate.

Client Credentials

The client credentials grant type is used when the system authenticating to the API is not on behalf of a user. Backend system to system integrations shall use the client credentails grant type. An explaination of the client credentials grant type and access token flow can be found at https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/.

OAuth2

The Everactive API uses OAuth2 to authenticate and generate a Bearer token to authorize API endpoints. External clients must use the client_credentials flow to authenticate. The expectation is the client_secret value is protected at all times. It must not be used in a mobile application or web application as it is not possible to protect the secret in these types of applications.

Example client_credentials grant_type request body:

{
  "client_id": "the_client_id",
  "client_secret": "the_client_secret",
  "grant_type": "client_credentials"
}
Security Scheme Type: OAuth2
Flow type: clientCredentials
Token URL: https://api.data.everactive.com/auth/token
Scopes:
  • super-admin -

    full access to all API endpoints

  • integration-partner -

    access to all public API endpoints

  • customer-admin -

    full access to API endpoints related to the customer the client belongs to

  • user -

    limited access to endpoints related to the customer the client belongs to

Request / Response body

All Everactive API requests and responses use JSON for the body*. No other data formats are accepted or provided (e.g. XML).

* The POST /files endpoint handles file uploads, so it requires a multipart form for the body (Content-Type: multipart/form-data).

Response Body Wrapper

All responses are wrapped in an object with the primary payload in the data property. Additional properties may be provided depending on the type of payload returned, specifically error conditions and pagination information for lists of data.

Pagination Info

Responses returning lists of data will have an Array in the data property and an additional paginationInfo object with the following format:

{
  "paginationInfo": {
    "page": 1,
    "pageSize": 50,
    "totalItems": 153,
    "totalPages": 4
  }
}

Errors

Requests that result in an error condition will have the following format (Note: the values provided are an example, specific errors result in specific code and message values):

{
  "code": "error_validation",
  "message": "Validation error.",
  "errors": [
    "code": "err_invalid_mac_address",
    "field": "sensor.macAddress",
    "message": "no:ta:re:al:ma:c0 is an invalid MAC Address"
  ]
}

Webhooks

The Everactive API allows clients to subscribe to updates for certain events.

When an event is detected, Everactive's webhook sends a an HTTP POST request to an endpoint you designated when creating your subscription. The details specific to the event are transferred as a JSON payload in the POST body.

Security

Webhook endpoints are required to use HTTPS. Additionally, all subscriptions are saved with a generated webhook secret. The generated secret is used to sign the request using http signatures (https://tools.ietf.org/id/draft-cavage-http-signatures-12.html). You must store the generated secret and validate each POST received was signed correctly using the secret.

Each request body is hashed using an SHA-256 algorithm with the webhook secret as the key and sent as the Digest header. The Digest header is used as part of the signature, and can also be used to verify the request used the correct webhook secret.

Signature Verification Details

Given the following request (body is omitted)

POST / HTTP/1.1
Content-Length: 385
Date: Sun, 27 Sep 2020 06:25:56 EDT
Digest: SHA-256=CUqnzEfLL8k73aT7e1R55yCQ6VAM70ZfDg9AMzJvPHM=
Host: localhost:3000
Signature: keyId="subscription-id-1",algorithm="hmac-sha256",
    signature="m7lO3Xld1ESjZTMX+Hg2njRXTQO3QK342dHd2x7Dbo0=",
    headers="(request-target) date digest host content-length"

The receiving client should construct a signing string as follows (+ "\n" added for clarity):

(request-target) post / + "\n"
date: Sun, 27 Sep 2020 06:25:56 EDT + "\n"
digest: SHA-256=CUqnzEfLL8k73aT7e1R55yCQ6VAM70ZfDg9AMzJvPHM= + "\n"
host: localhost:3000 + "\n"
content-length: 385

Using the secret provided when the subscription was created, hash the above string using sha256 and compare the hash generated on the client with the signature value provided in the Signature header. If they do not match the request is not valid.

To prevent replay attacks the Date header should be checked against the actual time with an allowance for clock skew. Since there is no hard rule for an allowable amount of time offset, it's recommended to reject any requests where the Date header is off by more than 300 seconds in either direction from the current time.

Specifics will be language dependent. There are also libraries available to verify http signatures. Everactive has used the following libraries:

Others are available, covering many languages.

Webhook Event Types

Everactive offers two event types for a webhook subscription at this time.

Machine Alarm State Change

The Machine Alarm State Change event is triggered when the alarm state of a monitored machine changes (e.g. Good to Alarm). The Everactive API will POST the following body when this event is triggered:

{
  "eventId": "alarm-state-change-event-id-1",
  "eventTimestamp": 1638566877,
  "integrationInfo": {
    "assetId": "asset-id-2",
    "name": "Asset 2"
  },
  "equipmentName": "Pump 2 Motor",
  "facility": "facility",
  "location": "location",
  "machineEndAlarmState": "Good",
  "machineId": "machine-id",
  "machineDetailUrl": "https://api.data.everactive.com/v2020-07/machines/machine-id",
  "machineInsightsUrl": "https://insights.everactive.com/machine/machine-id",
  "machineStartAlarmState": "Alarm",
  "machineType": "Motor",
  "sensorMacAddress": "ca:fe:a1:aa:01:00:02:03"
}

Note: The integrationInfo property is optional, and will be populated with the assetId and name properties you provided via the Everactive REST API when the steam trap was created or updated. If these properties were never set, integrationInfo will be omitted.

Valid Machine Alarm State Values

  • Acknowledged - The machine was in an alarm state and an Insights user marked it as acknowledged.
  • Alarm - The machine is in an alarm state.
  • Good - The machine is operating normally.

Steam Trap State Change

The Steam Trap State Change event is triggered when the state of a monitored trap changes (e.g. Good to Blowthrough). The Everactive API will POST the following body when this event is triggered:

{
  "eventId": "state-change-event-id-1",
  "eventTimestamp": 1600878991,
  "integrationInfo": {
    "assetId": "asset-id-1",
    "name": "Asset 1"
  },
  "facility": "facility",
  "location": "location",
  "sensorMacAddress": "ca:fe:00:01:02:03",
  "serviceTag": "service-tag",
  "trapEndState": "Blowthough",
  "trapDetailUrl": "https://api.data.everactive.com/v2020-07/steamtraps/steam-trap-id",
  "trapID": "steam-trap-id",
  "trapInsightsUrl": "https://insights.everactive.com/steamtrap/steam-trap-id",
  "trapStartState": "Good"
}

Note: The integrationInfo property is optional, and will be populated with the assetId and name properties you provided via the Everactive REST API when the steam trap was created or updated. If these properties were never set, integrationInfo will be omitted.

Valid steam trap states:

  • Blowthrough - Failure
  • Good - Good
  • Intermittent Blowthrough - Light - Light
  • Intermittent Blowthrough - Medium - Medium
  • Intermittent Blowthrough - Heavy - Heavy
  • Leaking By - Leaking
  • Unexpected Cold Condition - Cold

Files

Endpoints and components related to files.

upload a file

Upload a file and attach it to an existing entity.

If the request references more than one entity, the API will return a validation error. If the entity does not exist, or if the requester does not have access to the entity, the API will return an authorization error.

If the file is too large, the API will return a validation error.

The API also returns a validation error if the entity that the file is being attached to already has the maximum number of attachments allowed by the backend.

Authorizations:
OAuth2
Request Body schema: multipart/form-data

A request to upload a new file.

gatewayIdOrSerialNumber
string

Specifies the Gateway that the file should be attached to.

sensorIdOrMac
string

Specifies the Sensor that the file should be attached to.

steamTrapId
string <uuid>

Specifies the Steam Trap that the file should be attached to.

machineId
string <uuid>

Specifies the Machine that the file should be attached to.

caption
string

A user-facing description for the file.

isProfileImage
string
Default: false

A boolean specifying that this file should be set as the entity's profile image.

file
required
string <binary>

The contents of the file, including its filename and content type in the block.

Responses

Response samples

Content type
application/json
{}

get files

Returns a paginated list of files that the client is authorized to view, for the given query parameter criteria.

Authorizations:
OAuth2
query Parameters
fileName
string
Example: fileName=Steam Trap Photo.jpeg

Filter the files using a LIKE comparison with the file name property.

mediaType
string
Example: mediaType=image/jpeg

Filter the list of files returned using a LIKE comparison with the file media type property.

gateway.id
string <uuid>
Example: gateway.id=bcf992bf-bb5e-410d-bd9e-a25c2f563ca4

Filter the list of files returned by the id of the gateway they're attached to. An exact match is used for this filter.

sensor.id
string <uuid>
Example: sensor.id=41ff0192-ffa1-4b0d-a750-9ee5ce77701a

Filter the list of files returned by the ID of the sensor they're attached to. An exact match is used for this filter.

steamTrap.id
string <uuid>
Example: steamTrap.id=919ea836-7bc7-4f65-a02a-0230b25ddc33

Filter the list of files returned by the ID of the steam trap they're attached to. An exact match is used for this filter.

machine.id
string <uuid>
Example: machine.id=53352f61-820e-4840-840f-fea0e699c08c

Filter the list of files returned by the ID of the machine they're attached to. An exact match is used for this filter.

page
required
integer <int32> >= 1
Default: 1
Example: page=1

A one-based index for the first page number to return from a paginated call.

pageSize
integer <int32> >= 1
Default: 50
Example: pageSize=25

The maximum number of items to return per page.

sortBy
string
Default: "uploadedAtTimestamp"
Enum: "fileName" "mediaType" "fileSize" "uploadedAtTimestamp" "deletedAtTimestamp" "deletedReason" "gateway.id" "gateway.name" "gateway.serialNumber" "sensor.id" "sensor.macAddress" "steamTrap.id" "machine.id"
Example: sortBy=uploadedAtTimestamp

Indicate what field should be used to sort the returned list of files. If omitted the files are returned in an arbitrary order.

sortDir
string
Enum: "asc" "desc"
Example: sortDir=asc

The direction to sort the list of results, ascending or descending.

Responses

Response samples

Content type
application/json
{
  • "data": [],
  • "paginationInfo": {
    }
}

get file metadata

Returns a single metadata record that describes an uploaded file.

Authorizations:
OAuth2
path Parameters
fileId
required
string <uuid>
Example: 00c0cd34-e710-4bc0-8044-15cfd931b923

The UUID identifier of the file.

Responses

Response samples

Content type
application/json
{}

update file metadata

Updates the user-editable metadata for a single file.

Authorizations:
OAuth2
path Parameters
fileId
required
string <uuid>
Example: 00c0cd34-e710-4bc0-8044-15cfd931b923

The UUID identifier of the file.

Request Body schema: application/json

A request to update the user-editable metadata for a single file.

fileName
string

The name of the file, including extension user wishes to update.

isProfileImage
boolean

Specifies whether the file should be set as the profile image for the entity it's attached to.

caption
string

A user-facing description for the file.

Responses

Request samples

Content type
application/json
{
  • "fileName": "SteamTrap.jpg",
  • "isProfileImage": true,
  • "caption": "string"
}

Response samples

Content type
application/json
{}

soft delete file

Soft deletes a single file by id. Optionally accepts a reason for deleting as the body.

Authorizations:
OAuth2
path Parameters
fileId
required
string <uuid>
Example: 00c0cd34-e710-4bc0-8044-15cfd931b923

The UUID identifier of the file.

Request Body schema: application/json

A request to delete a single file (pass in delete reason).

deletedReason
string

The reason the file was deleted.

Responses

Request samples

Content type
application/json
{
  • "deletedReason": "Uploaded by accident."
}

Response samples

Content type
application/json
Example
{
  • "code": "error_validation",
  • "message": "Validation error.",
  • "errors": [
    ]
}

Gateway

Endpoints and components related to gateways.

get gateways

Return a list of gateways the client is authorized to view. Super-admin type users will receive all gateways unless the customerId query parameter is included in the request.

Authorizations:
OAuth2
query Parameters
flavor
string
Enum: "production" "virtual"
Example: flavor=production

Filter the gateways returned by the gateway flavor. An exact match is used for this filter.

hazardousLocationClassification
string (Hazardous Location Classification)
Enum: "C1D1" "C1D2"
Example: hazardousLocationClassification=C1D1

Indicates if the asset is located in an environment or location designated with a hazardous location classification.

id
string <uuid>
Example: id=bcf992bf-bb5e-410d-bd9e-a25c2f563ca4

Filter the gateways returned by the gateway id. An exact match is used for this filter.

location
string
Example: location=mezzanine

Filter the gateways using a LIKE comparison with the location property.

name
string
Example: name=East Mezzanine 3AG32B5

Filter the gateways using a LIKE comparison with the name property.

page
required
integer <int32> >= 1
Default: 1
Example: page=1

A one-based index for the first page number to return from a paginated call.

pageSize
integer <int32> >= 1
Default: 50
Example: pageSize=25

The maximum number of items to return per page.

serialNumber
string
Example: serialNumber=3AG32B5

Filter the gateways using a LIKE comparison with the serialNumber property.

softwareVersion
string
Example: softwareVersion=v2.0.1

Filter the gateways using a LIKE comparison with the softwareVersion property.

sortBy
string
Default: "lastReading"
Enum: "autoAuthorizeExistingSensors" "canSupportEvernet2" "configSchema" "customer.name" "deploymentStatus" "enableSSH" "enableWakeup" "evernet1Settings.enabled" "evernet2Settings.beaconOffset" "evernet2Settings.panId" "flavor" "hazardousLocationClassification" "id" "lastDailyStatus" "lastReading" "lastStatus" "location" "name" "serialNumber" "softwareVersion" "status"
Example: sortBy=lastReading

Indicate what field should be used to sort the returned list of gateways. If omitted the gateway's are returned with a descending sort order on the lastReading timestamp.

sortDir
string
Enum: "asc" "desc"
Example: sortDir=asc

The direction to sort the list of results, ascending or descending.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paginationInfo": {
    }
}

Machine

Endpoints and components related to machines.

get machines

Retrieve a list of machines the user is authorized to view. The returned list of machines can be filtered by various fields using optional query parameters. If more than one filter value is included the filtering is combined with an and statement meaning the returned traps must meet all filtering criteria.

Authorizations:
OAuth2
query Parameters
alarmState
string
Enum: "Good" "Acknowledged" "Alarm"

Filter the machines returned by their current alarm state. Allowed values are Good, Acknowledged, and Alarm. Multiple values can be passed as a comma separated value (e.g. &alarmState=Good,Acknowledged).

alarmStateUserName
string
Example: alarmStateUserName=pat

Filter the machines returned by the alarmStateUserName property. The value is filtered using a LIKE comparison statement.

equipmentName
string
Example: equipmentName=Saw Pump

Filter the machines returned by the equipmentName property. The value is filtered using a LIKE comparison statement.

facility
string
Example: facility=River West

Filter the machines returned by the facility property. The value is filtered using a LIKE comparison statement.

hazardousLocationClassification
string (Hazardous Location Classification)
Enum: "C1D1" "C1D2"
Example: hazardousLocationClassification=C1D1

Indicates if the asset is located in an environment or location designated with a hazardous location classification.

location
string
Example: location=Basement Pump Room

Filter the machines returned by the location property. The value is filtered using a LIKE comparison statement.

machineType
string
Example: machineType=pump

Filter the machines returned by the machineType property. The value is filtered using a LIKE comparison statement.

manufacturer
string
Example: manufacturer=ACME

Filter the machines returned by the manufacturer property. The value is filtered using a LIKE comparison statement.

page
required
integer <int32> >= 1
Default: 1
Example: page=1

A one-based index for the first page number to return from a paginated call.

pageSize
integer <int32> >= 1
Default: 50
Example: pageSize=25

The maximum number of items to return per page.

sensor.gatewaySerialNumber
string
Example: sensor.gatewaySerialNumber=3AG32B5

Filter the machines returned by the sensor gatewaySerialNumber property of the last reading. The value is filtered using a LIKE comparison statement.

sensor.id
string <uuid>
Example: sensor.id=f333578c-ba56-40dd-a5da-eb59e9716be2

Filter the machines returned by the sensor id. An exact match is used effectively limiting the number of machines that will be returned to one.

sensor.lastAssociationGatewaySerial
string
Example: sensor.lastAssociationGatewaySerial=AP24210094

Filter the machines returned by the sensor gateway serial of the last association using a LIKE comparison statement.

sensor.lastFirmwareVersion
string
Example: sensor.lastFirmwareVersion=silverglade/release_0.2.0_rc2

Filter the machines returned by the sensor last firmware version using a LIKE comparison statement.

sensor.lastPartNumber
string
Example: sensor.lastPartNumber=211600732

Filter the machines returned by the sensor last part number using a LIKE comparison statement.

sensor.lastSerialNumber
string
Example: sensor.lastSerialNumber=211600191

Filter the machines returned by the sensor last serial number using a LIKE comparison statement.

sensor.macAddress
string
Example: sensor.macAddress=0b:54

Filter the machines returned by the sensor mac address property. The value is filtered using a LIKE comparison statement.

sensor.manufacturedFirmwareVersion
string
Example: sensor.manufacturedFirmwareVersion=silverglade/release_0.2.0_rc2

Filter the machines returned by the sensor manufactured firmware version using a LIKE comparison statement.

sensor.productName
string
Example: sensor.productName=MVM Eversensor 2

Filter the machines returned by the sensor product name using a LIKE comparison statement.

sensor.status
string
Example: sensor.status=good

Filter the machines returned by the sensor status property. The value is filtered using a LIKE comparison statement.

sensor.installed
boolean

Filter the machines by if a sensor is currently installed or not. If set to true only machines with a sensor currently installed will be returned. If set to false only machines without a sensor will be returned.

sortBy
string
Enum: "alarmState" "alarmStateTimestamp" "alarmStateUserName" "customer.name" "equipmentName" "facility" "id" "hazardousLocationClassification" "location" "machineType" "manufacturer" "sensor.xAxisMaxAcceleration" "sensor.yAxisMaxAcceleration" "sensor.zAxisMaxAcceleration" "sensor.gatewaySerialNumber" "sensor.id" "sensor.lastAssociation" "sensor.lastAssociationGatewaySerial" "sensor.lastCondensateTemp" "sensor.lastInfo" "sensor.lastInfoFirmwareVersion" "sensor.lastInfoPartNumber" "sensor.lastInfoSerialNumber" "sensor.lastReading" "sensor.macAddress" "sensor.manufacturedFirmwareVersion" "sensor.productName" "sensor.overallXVibration" "sensor.overallYVibration" "sensor.overallZVibration" "sensor.status"
Example: sortBy=sensor.lastReading

The field to sort the results. If the value passed does not match any of the valid options or the sortBy query parameter is omitted the results will be returned sorted by sensor.lastReading in descending order.

sortDir
string
Enum: "asc" "desc"
Example: sortDir=asc

The direction to sort the list of results, ascending or descending.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paginationInfo": {
    },
  • "listSummary": {
    }
}

create machine

Create a new machine

Authorizations:
OAuth2
Request Body schema: application/json

A machine to create (or update).

bearings
string

the type of bearings in this machine

catalogNumber
string

manufacturer's catalog/model number for this machine

certifiedCompliant
string

this machine's compliance certificate number

codeLetter
string (MachineCodeLetter)
Enum: "A" "B" "C" "D" "E" "F" "G" "H" "J" "K" "L" "M" "N" "P" "R" "S" "T" "U" "V"
designLetter
string (MachineDesignLetter)
Enum: "A" "B" "C" "D"

motor design letter

driveEnd
string

machine drive end bearing type

enclosureType
string (MachineEnclosureType)
Enum: "ODP" "TEFC" "TENV" "TEAO" "TEWD" "TEHS" "EXPL" "HAZ"

machine enclosure type

equipmentName
required
string

human-readable name of this machine

facility
required
string

the facility in which this machine is located

object (MachineHealthFFTThresholds)

FFT threshold values object for a machine

frame
string (MachineNEMAFrameList)
Enum: "42C" "48" "48C" "48H" "56" "56C" "56H" "56HZ" "56J" "66" "140T" "142AT" "143AT" "143JM" "143JP" "143T" "143TC" "143TR" "144AT" "145AT" "145JM" "145JP" "145T" "145TC" "145TR" "146AT" "146ATC" "147AT" "148AT" "149AT" "1410AT" "1411AT" "1412AT" "1412ATC" "162AT" "163AT" "164AT" "165AT" "166AT" "167AT" "168AT" "169AT" "1610AT" "182" "L182ACY" "182AT" "L182AT" "182JM" "182JP" "182T" "182TC" "182TR" "183AT" "184" "184AT" "184JM" "184JP" "184TC" "184T" "184TR" "185AT" "186ACY" "186AT" "L186AT" "186ATC" "187AT" "188AT" "189AT" "189ATC" "1810AT" "203" "204" "213" "213AT" "213JM" "213JP" "213T" "213TC" "213TR" "214AT" "215" "215AT" "215JM" "215JP" "215T" "215TC" "215TR" "216AT" "217AT" "218AT" "219AT" "219ATC" "2110AT" "2110ATC" "224" "225" "253AT" "254" "254AT" "254T" "254TC" "254TR" "254U" "255AT" "256AT" "256T" "256TC" "256TR" "256U" "257AT" "258AT" "259AT" "283AT" "284" "284AT" "284T" "284TC" "284TR" "284U" "285AT" "286AT" "286T" "286TC" "286TR" "286TS" "286U" "287AT" "288AT" "289AT" "323AT" "324" "324AT" "324TR" "324TS" "324U" "325AT" "326" "326AT" "326T" "326TR" "326TS" "326U" "327AT" "328AT" "329AT" "363AT" "364" "364AT" "364S" "364T" "364TR" "364TS" "364U" "365" "365AT" "365T" "324T" "365TR" "365TS" "365U" "366AT" "367AT" "368AT" "369AT"
hazardousLocationClassification
string (Hazardous Location Classification)
Enum: "C1D1" "C1D2"

Indicates if the asset is located in an environment or location designated with a hazardous location classification.

horsepower
number <double>

motor horsepower

insulationClass
string (MachineInsulationClass)
Enum: "A" "B" "F" "H"

wiring insulation class

object (IntegrationInfo)

Information for an item that is specific to an external integration system. This information is used to allow integration of assets across multiple systems.

lineFrequency
number <double>

expected input AC power frequency (Hz)

location
required
string

physical location of the machine within the facility (see above)

machineType
required
string (MachineTypeList)
Enum: "Blower" "Compressor" "Fan" "Gear Box" "Pump" "Motor" "Other"

type of this machine

manufacturer
string

this machine's manufacturer

maxAmbientTemperature
number <double>

rated maximum safe ambient operating temperature (degrees C)

NEMANominalEfficiency
number <double>

NEMA nominal efficiency percentage

oppositeDriveEnd
string

machine opposite drive end bearing type

phases
integer <int64> (MachinePhases)
Enum: 1 3

number of AC power phases

powerFactor
number <double>

motor power factor

ratedFullLoadAmps
number <double>

amperage rating at full load

ratedFullLoadRPMs
number <double>

rotational speed at full load (revolutions per minute)

ratedVoltage
number <double>

voltage rating

ratingDuty
string

duty-cycle rating

serviceFactor
number

service factor multiplier for the motor

specNumber
string

machine serial number

object (MachineHealthThresholds)
customerId
string <uuid>

The customer the machine is associated with. This property can only be set by clients with the super-admin privilege.

object

The sensor currently installed on the machine.

Responses

Request samples

Content type
application/json
{
  • "bearings": "Ball",
  • "catalogNumber": "A12345B",
  • "certifiedCompliant": "CC1234",
  • "codeLetter": "A",
  • "designLetter": "A",
  • "driveEnd": "65BCO3J30X",
  • "enclosureType": "TEFC",
  • "equipmentName": "Aspiration Gas Line 1 - Blower Motor 1 Inboard Vertical - 2V",
  • "facility": "Charlottesville Gas Plant",
  • "fftThresholds": {
    },
  • "frame": "364T",
  • "hazardousLocationClassification": "C1D1",
  • "horsepower": 250,
  • "insulationClass": "B",
  • "integrationInfo": {
    },
  • "lineFrequency": 60.5,
  • "location": "Room 324A",
  • "machineType": "Motor",
  • "manufacturer": "Reliance",
  • "maxAmbientTemperature": 40.3,
  • "NEMANominalEfficiency": 96.2,
  • "oppositeDriveEnd": "65BCO3J30X",
  • "phases": 1,
  • "powerFactor": 91.5,
  • "ratedFullLoadAmps": 267,
  • "ratedFullLoadRPMs": 3575,
  • "ratedVoltage": 460,
  • "ratingDuty": "CONT",
  • "serviceFactor": 1.15,
  • "specNumber": "183AD82F",
  • "thresholds": {
    },
  • "customerId": "54c32003-0d20-4c41-a8a5-3d24e4997975",
  • "sensor": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get machine alarm status trend for a certain time range

Retrieve a history of number of machines per status daily between a time range.

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

get machines thresholdcrossings

Retrieve a summary of total machine threshold crossings for all machines the user is authorized to view. The returned summary of machine threshold crossings can be filtered by different fields using optional query parameters.

Authorizations:
OAuth2
query Parameters
page
required
integer <int32> >= 1
Default: 1
Example: page=1

A one-based index for the first page number to return from a paginated call.

pageSize
integer <int32> >= 1
Default: 50
Example: pageSize=25

The maximum number of items to return per page.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paginationInfo": {
    }
}

delete machine

Delete a machine. This operation is a "hard" delete of the machine and can not be reverted. Customer admin users are limited to deleting machines assigned to the same customer.

If the machine has an installed sensor, the sensor will NOT be deleted as part of this operation.

Authorizations:
OAuth2
path Parameters
machineId
required
string <uuid>
Example: e5d80a07-7d04-4873-a5b8-169f4cb02962

The machine id.

Responses

Response samples

Content type
application/json
Example
{
  • "code": "error_validation",
  • "message": "Validation error.",
  • "errors": [
    ]
}

get machine

Get details for a machine using the Everactive machine ID.

Authorizations:
OAuth2
path Parameters
machineId
required
string <uuid>
Example: e5d80a07-7d04-4873-a5b8-169f4cb02962

The machine id.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update machine

Updates machine details. This endpoint is to update the machine properties and does not change customer association, install or uninstall a sensor, or update the machine alarm state.

Authorizations:
OAuth2
path Parameters
machineId
required
string <uuid>
Example: e5d80a07-7d04-4873-a5b8-169f4cb02962

The machine id.

Request Body schema: application/json

A machine to update.

bearings
string

the type of bearings in this machine

catalogNumber
string

manufacturer's catalog/model number for this machine

certifiedCompliant
string

this machine's compliance certificate number

codeLetter
string (MachineCodeLetter)
Enum: "A" "B" "C" "D" "E" "F" "G" "H" "J" "K" "L" "M" "N" "P" "R" "S" "T" "U" "V"
designLetter
string (MachineDesignLetter)
Enum: "A" "B" "C" "D"

motor design letter

driveEnd
string

machine drive end bearing type

enclosureType
string (MachineEnclosureType)
Enum: "ODP" "TEFC" "TENV" "TEAO" "TEWD" "TEHS" "EXPL" "HAZ"

machine enclosure type

object (SensorMHMReading)

A single reading from an MHM Eversensor.

equipmentName
required
string

human-readable name of this machine

facility
required
string

the facility in which this machine is located

object (MachineHealthFFTThresholds)

FFT threshold values object for a machine

frame
string (MachineNEMAFrameList)
Enum: "42C" "48" "48C" "48H" "56" "56C" "56H" "56HZ" "56J" "66" "140T" "142AT" "143AT" "143JM" "143JP" "143T" "143TC" "143TR" "144AT" "145AT" "145JM" "145JP" "145T" "145TC" "145TR" "146AT" "146ATC" "147AT" "148AT" "149AT" "1410AT" "1411AT" "1412AT" "1412ATC" "162AT" "163AT" "164AT" "165AT" "166AT" "167AT" "168AT" "169AT" "1610AT" "182" "L182ACY" "182AT" "L182AT" "182JM" "182JP" "182T" "182TC" "182TR" "183AT" "184" "184AT" "184JM" "184JP" "184TC" "184T" "184TR" "185AT" "186ACY" "186AT" "L186AT" "186ATC" "187AT" "188AT" "189AT" "189ATC" "1810AT" "203" "204" "213" "213AT" "213JM" "213JP" "213T" "213TC" "213TR" "214AT" "215" "215AT" "215JM" "215JP" "215T" "215TC" "215TR" "216AT" "217AT" "218AT" "219AT" "219ATC" "2110AT" "2110ATC" "224" "225" "253AT" "254" "254AT" "254T" "254TC" "254TR" "254U" "255AT" "256AT" "256T" "256TC" "256TR" "256U" "257AT" "258AT" "259AT" "283AT" "284" "284AT" "284T" "284TC" "284TR" "284U" "285AT" "286AT" "286T" "286TC" "286TR" "286TS" "286U" "287AT" "288AT" "289AT" "323AT" "324" "324AT" "324TR" "324TS" "324U" "325AT" "326" "326AT" "326T" "326TR" "326TS" "326U" "327AT" "328AT" "329AT" "363AT" "364" "364AT" "364S" "364T" "364TR" "364TS" "364U" "365" "365AT" "365T" "324T" "365TR" "365TS" "365U" "366AT" "367AT" "368AT" "369AT"
hazardousLocationClassification
string (Hazardous Location Classification)
Enum: "C1D1" "C1D2"

Indicates if the asset is located in an environment or location designated with a hazardous location classification.

horsepower
number <double>

motor horsepower

insulationClass
string (MachineInsulationClass)
Enum: "A" "B" "F" "H"

wiring insulation class

lineFrequency
number <double>

expected input AC power frequency (Hz)

location
required
string

physical location of the machine within the facility (see above)

machineType
required
string (MachineTypeList)
Enum: "Blower" "Compressor" "Fan" "Gear Box" "Pump" "Motor" "Other"

type of this machine

manufacturer
string

this machine's manufacturer

maxAmbientTemperature
number <double>

rated maximum safe ambient operating temperature (degrees C)

NEMANominalEfficiency
number <double>

NEMA nominal efficiency percentage

oppositeDriveEnd
string

machine opposite drive end bearing type

phases
integer <int64> (MachinePhases)
Enum: 1 3

number of AC power phases

powerFactor
number <double>

motor power factor

object (File Minimal)
ratedFullLoadAmps
number <double>

amperage rating at full load

ratedFullLoadRPMs
number <double>

rotational speed at full load (revolutions per minute)

ratedVoltage
number <double>

voltage rating

ratingDuty
string

duty-cycle rating

serviceFactor
number <double>

service factor multiplier for the motor

specNumber
string

machine serial number

object (MachineHealthThresholds)

Responses

Request samples

Content type
application/json
{
  • "bearings": "Ball",
  • "catalogNumber": "A12345B",
  • "certifiedCompliant": "CC1234",
  • "codeLetter": "A",
  • "designLetter": "A",
  • "driveEnd": "65BCO3J30X",
  • "enclosureType": "TEFC",
  • "lastReading": {
    },
  • "equipmentName": "Aspiration Gas Line 1 - Blower Motor 1 Inboard Vertical - 2V",
  • "facility": "Charlottesville Gas Plant",
  • "fftThresholds": {
    },
  • "frame": "364T",
  • "hazardousLocationClassification": "C1D1",
  • "horsepower": 250,
  • "insulationClass": "B",
  • "lineFrequency": 60.5,
  • "location": "Room 324A",
  • "machineType": "Motor",
  • "manufacturer": "Reliance",
  • "maxAmbientTemperature": 40.3,
  • "NEMANominalEfficiency": 96.2,
  • "oppositeDriveEnd": "65BCO3J30X",
  • "phases": 1,
  • "powerFactor": 91.5,
  • "profileImage": {
    },
  • "ratedFullLoadAmps": 267,
  • "ratedFullLoadRPMs": 3575,
  • "ratedVoltage": 460,
  • "ratingDuty": "CONT",
  • "serviceFactor": 1.15,
  • "specNumber": "183AD82F",
  • "thresholds": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get machine history

Retrieve a descending event date order list of events for a machine.

Authorizations:
OAuth2
path Parameters
machineId
required
string <uuid>
Example: ac014dec-df5d-4879-84af-dfe8cb268187

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paginationInfo": {
    }
}

update machine sensor installation

Install a sensor on a machine, or remove a sensor from a machine.

If the {sensorIdOrMac} value in the path does not match the currently installed sensor on the machine the existing sensor installation will be ended with an endTimestamp matching the passed startTimestamp.

If the {sensorIdOrMac} value matches the currently installed sensor on the machine, the installation event will be updated with the passed values. Specifically if an endTimestamp is passed the sensor will be "removed" from the machine by ending the sensor installation event.

If the {sensorIdOrMac} value is installed on another piece of equipment an error will be returned. This endpoint will not "move" a sensor from one piece of equipment to another. The existing installation event must be ended before a sensor can be installed on a new piece of equipment.

Authorizations:
OAuth2
path Parameters
machineId
required
string <uuid>
Example: e5d80a07-7d04-4873-a5b8-169f4cb02962

The machine id.

sensorIdOrMac
required
string
Example: 00:a0:50:0c:2b:23

The id or MAC address of the sensor being installed or removed from the machine.

Request Body schema: application/json

A request to install a sensor on a piece of equipment or to end an existing installation.

endTimestamp
integer <int64>

The timestamp when the sensor was removed from the equipment. Including the endTimestamp value will effectively uninstall the sensor from a piece of equipment.

sensorIdOrMac
required
string

The id or MAC address of the sensor being installed or uninstalled.

startTimestamp
required
integer <int64>

The timestamp when the sensor was installed on the equipment.

installationNotes
string

Notes about the installation of the sensor.

tempProbesSwapped
boolean

A flag specific to STM sensors indicating the condensate and steam temperature probes were swapped when installed. This flag is used to correct the mapping of temperatures so the values are returned correctly from the API when retrieving time series data for an STM sensor.

Responses

Request samples

Content type
application/json
{
  • "endTimestamp": 1597018117,
  • "sensorIdOrMac": "00:a0:50:0c:2b:23",
  • "startTimestamp": 1597908117,
  • "installationNotes": "Installed on the north side of the machine.",
  • "tempProbesSwapped": false
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get machine timeseries

Retrieve a list of Eversensor readings for a machine. This endpoint is intended to provide data for a user to view. It is not intended as a method to download large volumes of sensor reading data. As such, the maximum number of data points that will be returned from this endpoint is 5000.

Readings will only be provided for time periods the machine has a sensor installed. If the startTime requested is prior to any sensors installed it will be adjusted to match the earliest possible sensor reading. If the endTime provided is after any sensors installed it will be adjusted to match the last possible sensor reading.

If the requested time period will produce a payload that exceeds the maximum it will behave in one of two ways:

If a downsampleRate has been provided an error will be returned to the client explaining the requested parameters will exceed the maximum.

If no downsampleRate is specified the server will calculate a downsampleRate based upon default sensor settings that results in a result set close to the maximum number of data points. If a sensor is reporting with a non-default period (due to setup or environmental conditions) the actual number of returned sensor readings may deviate from the stated maximum.

The response payload will contain both the data and a summary of the start and end dates, the returned item count and the downsampleRate used.

The expected number of sensor readings is based upon a sensor returning a reading every minute, resulting in 1440 sensor readings per 24 hour period.

Authorizations:
OAuth2
path Parameters
machineId
required
string <uuid>
Example: ac014dec-df5d-4879-84af-dfe8cb268187
query Parameters
startTime
required
integer <int64> >= 0
Example: startTime=1591305631

The start time for the time series data. Inclusive. A UNIX timestamp, seconds from 1970-01-01.

endTime
integer <int64>
Example: endTime=1591305631

The end time for the time series data. Inclusive. A UNIX timestamp, seconds from 1970-01-01.

downsampleRate
integer <int32> > 0
Example: downsampleRate=300

The number of seconds for the downsample interval. (3600 = 1 hour).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "resultSetInfo": {
    }
}

get a list of all the available machine FTWF readings for a single machine for a for a specified time period

Retrieve a list of FTWF change in descending data order for a single machine for a specific time period.

Authorizations:
OAuth2
path Parameters
machineId
required
string <uuid>
Example: ac014dec-df5d-4879-84af-dfe8cb268187
query Parameters
sensor.id
string <uuid>
Example: sensor.id=f333578c-ba56-40dd-a5da-eb59e9716be2

Filter the FTWFs returned by the sensor id.

sensor.macAddress
string
Example: sensor.macAddress=0b:54

Filter the FTWFs returned by the sensor mac address property. The value is filtered using a LIKE comparison statement.

startTime
number
Example: startTime=1621442032

The UNIX timestamp of a start date range for a FTWF reading

endTime
number
Example: endTime=1603211632

The UNIX timestamp of an end date range for a FTWF reading

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paginationInfo": {
    }
}

get a single machine FTWF reading for a single machine

Retrieve a single FTWF reading for a single machine.

Authorizations:
OAuth2
path Parameters
machineId
required
string <uuid>
Example: ac014dec-df5d-4879-84af-dfe8cb268187
waveformId
required
string <uuid>
Example: ac014dec-df5d-4879-84af-dfe8cb268187

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Machine Alarm State

Endpoints and components related to machine alarm state change events.

get machine alarm state change event

Retrieve a single machine alarm state change event.

Authorizations:
OAuth2
path Parameters
machineId
required
string <uuid>
Example: ac014dec-df5d-4879-84af-dfe8cb268187
required
string or string
Example: 8afc9919-bd81-47da-915d-27c08d178389

The alarm state change event id for GET or the new alarm state for the machine, either Acknowledged or Good.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

set machine alarm state

Set the alarm state of a machine. The endpoint can only be used to acknowledge a machine in a state of 'Alarm' or to set the machine alarm state to 'Good'. Attempting to set the machine alarm state to 'Alarm' will be rejected.

Authorizations:
OAuth2
path Parameters
machineId
required
string <uuid>
Example: ac014dec-df5d-4879-84af-dfe8cb268187
required
string or string
Example: 8afc9919-bd81-47da-915d-27c08d178389

The alarm state change event id for GET or the new alarm state for the machine, either Acknowledged or Good.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Sensor

Endpoints and components related to sensors.

get sensors

Retrieve a list of sensors the user is authorized to view. The returned list of sensors can be filterd by various properties using optional query parameters. If more than one filter value is included the filtering is combined with an and statement meaning the returned sensors must meet all filtering criteria.

Authorizations:
OAuth2
query Parameters
id
string
Example: id=54c32

Filter the list by sensor id using a LIKE comparison statement.

installStatus
string
Enum: "available" "installed"
Example: installStatus=available

Filter the list based upon the current installation status of the sensor. available will return sensors that are not currently installed on a piece of equipment. installed will return sensors that are currently installed on a piece of equipment.

lastAssociationGatewaySerial
string
Example: lastAssociationGatewaySerial=AP24210094

Filter the list of sensors by gateway serial of the last association using a LIKE comparison statement.

lastFirmwareVersion
string
Example: lastFirmwareVersion=silverglade/release_0.2.0_rc2

Filter the list of sensors by last firmware version using a LIKE comparison statement.

lastPartNumber
string
Example: lastPartNumber=211600732

Filter the list of sensors by last part number using a LIKE comparison statement.

lastSerialNumber
string
Example: lastSerialNumber=211600191

Filter the list of sensors by last serial number using a LIKE comparison statement.

macAddress
string
Example: macAddress=00:a0:50:0c:2b:23

Filter the list of sensors by mac address using a LIKE comparison statement.

manufacturedFirmwareVersion
string
Example: manufacturedFirmwareVersion=silverglade/release_0.2.0_rc2

Filter the list of sensors by manufactured firmware version using a LIKE comparison statement.

productName
string
Example: productName=STM Eversensor 2

Filter the list of sensors by product name using a LIKE comparison statement.

page
required
integer <int32> >= 1
Default: 1
Example: page=1

A one-based index for the first page number to return from a paginated call.

pageSize
integer <int32> >= 1
Default: 50
Example: pageSize=25

The maximum number of items to return per page.

status
string
Example: status=good

Filter the sensors returned by the sensor status property using a LIKE comparison statement. Filtering is case-insensitive.

Possible sensor status values:

  • Configuration Error - Energy Aware - Extreme Temp Probe - Ambient - Extreme Temp Probe - Condensate - Extreme Temp Probe - Steam - Extreme Temp Probe - Teg - Extreme Temp - Surface Too Hot - Gateway Offline - Good - Harvesting Issue - Installed Cold - Long-term Offline - Never Installed - Not Installed - Not Reporting - Offline - Offline Poor RSSI - Offline w/ Power - Online - Service Needed - Service Needed - Harvesting Issue - Sleep - Sleep While Charging - Sleep While Discharging - Unknown
type
string

Filter the sensors returned by the type of sensor using a LIKE comparison statement.

sortBy
string
Enum: "customer.name" "id" "lastAssociation" "lastAssociation.gatewaySerial" "lastInfo" "lastInfo.firmwareVersion" "lastInfo.partNumber" "lastInfo.serialNumber" "lastReading" "macAddress" "manufacturedFirmwareVersion" "productName" "rssiUplink" "status" "type"
Example: sortBy=macAddress

The field to sort the results. If the value passed does not match any of the valid options or the sortBy query parameter is omitted the results will be returned sorted by lastReading in descending order.

sortDir
string
Enum: "asc" "desc"
Example: sortDir=asc

The direction to sort the list of results, ascending or descending.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paginationInfo": {
    }
}

get sensor

Get details for a sensor use ther sensor Everactive ID or the sensor MAC Address.

Authorizations:
OAuth2
path Parameters
sensorIdOrMac
required
string
Example: 00:a0:50:0c:2b:23

The sensor id or mac address.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Steam Trap

Endpoints and components related to steam traps.

get steam traps

Retrieve a list of steam traps the user is authorized to view. The returned list of steam traps can be filtered by various fields using optional query parameters. If more than one filter value is included the filtering is combined with an and statement meaning the returned traps must meet all filtering criteria.

Authorizations:
OAuth2
query Parameters
facility
string
Example: facility=River West

Filter the steam traps returned by the facility property. The value is filtered using a LIKE comparison statement.

hazardousLocationClassification
string (Hazardous Location Classification)
Enum: "C1D1" "C1D2"
Example: hazardousLocationClassification=C1D1

Indicates if the asset is located in an environment or location designated with a hazardous location classification.

isFailed
boolean
Example: isFailed=true

Filter the steam traps returned by current failure status. If set to true only traps currently in a failed status will be returned. If set to false only traps in a Good status will be returned. If omitted no filtering is performed on trap status.

location
string
Example: location=Basement Pump Room

Filter the steam traps returned by the location property. The value is filtered using a LIKE comparison statement.

manufacturer
string
Example: manufacturer=Armstrong

Filter the steam traps returned by the manufacturer property. The value is filtered using a LIKE comparison statement.

page
required
integer <int32> >= 1
Default: 1
Example: page=1

A one-based index for the first page number to return from a paginated call.

pageSize
integer <int32> >= 1
Default: 50
Example: pageSize=25

The maximum number of items to return per page.

sensor.gatewaySerialNumber
string
Example: sensor.gatewaySerialNumber=3AG32B5

Filter the steam traps returned by the sensor gatewaySerialNumber property of the last reading. The value is filtered using a LIKE comparison statement.

sensor.id
string <uuid>
Example: sensor.id=f333578c-ba56-40dd-a5da-eb59e9716be2

Filter the steam traps returned by the sensor id. An exact match is used effectively limiting the number of traps that will be returned to one.

sensor.installed
boolean

Filter the steam traps by if a sensor is currently installed or not. If set to true only steam traps with a sensor currently installed will be returned. If set to false only steam traps with out a sensor will be returned.

sensor.lastAssociationGatewaySerial
string
Example: sensor.lastAssociationGatewaySerial=AP24210094

Filter the steam traps returned by the sensor gateway serial of the last association using a LIKE comparison statement.

sensor.lastFirmwareVersion
string
Example: sensor.lastFirmwareVersion=silverglade/release_0.2.0_rc2

Filter the steam traps returned by the sensor last firmware version using a LIKE comparison statement.

sensor.lastPartNumber
string
Example: sensor.lastPartNumber=211600732

Filter the steam traps returned by the sensor last part number using a LIKE comparison statement.

sensor.lastSerialNumber
string
Example: sensor.lastSerialNumber=211600191

Filter the steam traps returned by the sensor last serial number using a LIKE comparison statement.

sensor.macAddress
string
Example: sensor.macAddress=0b:54

Filter the steam traps returned by the sensor mac address property. The value is filtered using a LIKE comparison statement.

sensor.manufacturedFirmwareVersion
string
Example: sensor.manufacturedFirmwareVersion=silverglade/release_0.2.0_rc2

Filter the steam traps returned by the sensor manufactured firmware version using a LIKE comparison statement.

sensor.productName
string
Example: sensor.productName=STM Eversensor 2

Filter the steam traps returned by the sensor product name using a LIKE comparison statement.

sensor.status
string
Example: sensor.status=good

Filter the steam traps returned by the sensor status property. The value is filtered using a LIKE comparison statement.

sortBy
string
Enum: "amountLost" "customer.name" "customer.status" "facility" "failureTimestamp" "hazardousLocationClassification" "id" "inletPressure" "location" "manufacturer" "model" "operationType" "orificeDiameter" "pipeSize" "sensor.gatewaySerialNumber" "sensor.id" "sensor.lastAmbientTemp" "sensor.lastAssociation" "sensor.lastAssociationGatewaySerial" "sensor.lastCondensateTemp" "sensor.lastHumidity" "sensor.lastInfo" "sensor.lastInfoFirmwareVersion" "sensor.lastInfoPartNumber" "sensor.lastInfoSerialNumber" "sensor.lastReading" "sensor.lastRSSIUplink" "sensor.lastSCAP" "sensor.lastSteamTemp" "sensor.lastVCAP" "sensor.macAddress" "sensor.manufacturedFirmwareVersion" "sensor.productName" "sensor.status" "steamState" "steamStateTimestamp" "svcTag" "trapApplication" "trapState" "trapType"
Example: sortBy=sensor.lastReading

The field to sort the results. If the value passed does not match any of the valid options or the sortBy query parameter is omitted the results will be returned sorted by sensor.lastReading in descending order.

sortDir
string
Enum: "asc" "desc"
Example: sortDir=asc

The direction to sort the list of results, ascending or descending.

steamState
string
Example: steamState=off

Filter the steam traps returned by the current steam state of the trap. The value is filtered using a LIKE comparison statement.

svcTag
string
Example: svcTag=UFA-345

Filter the steam traps by the steam trap svcTag property. The value is filtered using a LIKE comparison statement.

trapApplication
string
Example: trapApplication=Process Equipment

Filter the steam traps by the steam trap application property. The value is filtered using a LIKE comparison statement.

trapState
string
Example: trapState=blowthrough

Filter the steam traps by the steam trap state. The value is filtered using a LIKE comparison statement.

trapType
string
Example: trapType=Float

Filter the steam traps by the steam trap type property. The value is filtered using a LIKE comparison statement.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paginationInfo": {
    }
}

create / update steam trap

Create a new steam trap or update an existing steam trap if the passed sensor macAddress is associated with an existing steam trap in the Everactive system.

Note: If the macAddress is already associated with a steam trap, the steam trap will only be updated if the calling client has the appropriate permissions.

Authorizations:
OAuth2
Request Body schema: application/json

A steam trap to create or update.

customerId
string <uuid>

The customer the steam trap is associated with. This property can only be set by clients with the super-admin privilege.

object (IntegrationInfo)

Information for an item that is specific to an external integration system. This information is used to allow integration of assets across multiple systems.

required
object

The sensor currently installed on the steam trap. This value is required for non super-admin clients.

required
object

Details about the physical location and environment of the steam trap.

required
object

Property details of the trap itself.

Responses

Request samples

Content type
application/json
{
  • "customerId": "54c32003-0d20-4c41-a8a5-3d24e4997975",
  • "integrationInfo": {
    },
  • "sensor": {
    },
  • "siteDetail": {
    },
  • "trapDetail": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get steam trap

Get details for a steam trap using the Everactive trap ID.

Authorizations:
OAuth2
path Parameters
trapId
required
string <uuid>
Example: e5d80a07-7d04-4873-a5b8-169f4cb02962

The steam trap id.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update steam trap

Updates a steam trap details. This endpoint is to update the steam trap properties and does not change customer association, install or uninstall a sensor or update the steam trap or steam calculated state.

Authorizations:
OAuth2
path Parameters
trapId
required
string <uuid>
Example: e5d80a07-7d04-4873-a5b8-169f4cb02962

The steam trap id.

Request Body schema: application/json

The details of an existing steam trap to be updated.

id
required
string <uuid>

The Everactive id for the steam trap. The id value must match the value in the path.

required
object

Details about the physical location and environment of the steam trap.

required
object

Property details of the trap itself.

Responses

Request samples

Content type
application/json
{
  • "id": "e5d80a07-7d04-4873-a5b8-169f4cb02962",
  • "siteDetail": {
    },
  • "trapDetail": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get steam trap measurements

Retrieve a list of measurements made on a steam trap. The measurements are returned in descending order of when the measurement was taken (most recent first).

Authorizations:
OAuth2
path Parameters
trapId
required
string <uuid>
Example: e5d80a07-7d04-4873-a5b8-169f4cb02962
query Parameters
page
required
integer <int32> >= 1
Default: 1
Example: page=1

A one-based index for the first page number to return from a paginated call.

pageSize
integer <int32> >= 1
Default: 50
Example: pageSize=25

The maximum number of items to return per page.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paginationInfo": {
    }
}

create steam trap measurement

Create a new measurement record for the steam trap. The steam trap state may be updated if the state passed is a change from the current state of the steam trap.

Authorizations:
OAuth2
path Parameters
trapId
required
string <uuid>
Example: e5d80a07-7d04-4873-a5b8-169f4cb02962
Request Body schema: application/json

A measurement to store for a steam trap.

object

Details for any action taken that caused the measurement to be created. (e.g. Trap was replaced)

certainty
required
integer [ 1 .. 10 ]

How certain the measurement is. A subjective value between 1 (least certain) and 10 (most certain).

environmentalConditions
string

A brief description of the environmental conditions around the trap when the measurement was taken.

instrument
string

The instrument used to make the measurement.

instrumentSettings
string

The settings on the instrument (if applicable) when the measurement was taken.

notes
string

Additional notes about the measurement or the steam trap.

trapState
required
string (MeasurementSteamTrapState)
Enum: "Good" "Failed Blowthrough" "Failed Cold" "Failed Leaking By" "Intermittent Blowthrough - Light" "Intermittent Blowthrough - Medium" "Intermittent Blowthrough - Heavy" "Process Off" "N/A"

The measured state of the steam trap.

steamState
required
string (SteamState)
Enum: "On" "Off" "Unknown"

The state of the steam.

timestamp
required
integer <int64>

The unix timestamp when the measurement was taken.

Responses

Request samples

Content type
application/json
{
  • "actionDetail": {
    },
  • "certainty": 9,
  • "environmentalConditions": "hot and very dry",
  • "instrument": "Ultrasonic",
  • "instrumentSettings": "UE 9000",
  • "notes": "Two BTs",
  • "trapState": "Good",
  • "steamState": "On",
  • "timestamp": 1594124102
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete steam trap measurement

Delete a steam trap measurement.

Authorizations:
OAuth2
path Parameters
trapId
required
string <uuid>
Example: 65ebb46c-b0a0-11ea-b3de-0242ac130004
measurementId
required
string <uuid>
Example: 16c09dab-49d3-4024-ac23-d55602771048

Responses

Response samples

Content type
application/json
Example
{
  • "code": "error_validation",
  • "message": "Validation error.",
  • "errors": [
    ]
}

get steam trap history

Retrieve a descending event date order list of events for a steam trap.

Authorizations:
OAuth2
path Parameters
trapId
required
string <uuid>
Example: 65ebb46c-b0a0-11ea-b3de-0242ac130004

The steam trap id.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paginationInfo": {
    }
}

get steam trap sensor installations

Get a list of sensor install events for the steam trap in descending start date order.

Authorizations:
OAuth2
path Parameters
trapId
required
string <uuid>
Example: 65ebb46c-b0a0-11ea-b3de-0242ac130004

The steam trap id.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

update steam trap sensor installation

Install a sensor on a steam trap, or remove a sensor from a steam trap.

If the {sensorIdOrMac} value in the path does not match the currently installed sensor on the steam trap the existing sensor installation will be ended with an endTimestamp matching the passed startTimestamp.

If the {sensorIdOrMac} value matches the currently installed sensor on the steam trap, the installation event will be updated with the passed values. Specifically if an endTimestamp is passed the sensor will be "removed" from the steam trap by ending the sensor installation event.

If the {sensorIdOrMac} value is installed on another piece of equipment an error will be returned. This endpoint will not "move" a sensor from one piece of equipment to another. The existing installation event must be ended before a sensor can be installed on a new piece of equipment.

Authorizations:
OAuth2
path Parameters
trapId
required
string <uuid>
Example: 65ebb46c-b0a0-11ea-b3de-0242ac130004

The steam trap id.

sensorIdOrMac
required
string
Example: 00:a0:50:0c:2b:23

The id or MAC address of the sensor being installed or removed from the steam trap.

Request Body schema: application/json

A request to install a sensor on a piece of equipment or to end an existing installation.

endTimestamp
integer <int64>

The timestamp when the sensor was removed from the equipment. Including the endTimestamp value will effectively uninstall the sensor from a piece of equipment.

sensorIdOrMac
required
string

The id or MAC address of the sensor being installed or uninstalled.

startTimestamp
required
integer <int64>

The timestamp when the sensor was installed on the equipment.

installationNotes
string

Notes about the installation of the sensor.

tempProbesSwapped
boolean

A flag specific to STM sensors indicating the condensate and steam temperature probes were swapped when installed. This flag is used to correct the mapping of temperatures so the values are returned correctly from the API when retrieving time series data for an STM sensor.

Responses

Request samples

Content type
application/json
{
  • "endTimestamp": 1597018117,
  • "sensorIdOrMac": "00:a0:50:0c:2b:23",
  • "startTimestamp": 1597908117,
  • "installationNotes": "Installed on the north side of the machine.",
  • "tempProbesSwapped": false
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get steam trap timeseries

Retrieve a list of Eversensor readings for a steam trap. This endpoint is intended to provide data for a user to view. It is not intended as a method to download large volumes of sensor reading data. As such, the maximum number of data points that will be returned from this endpoint is 5000.

Readings will only be provided for time periods the trap has a sensor installed. If the startTime requested is prior to any sensors installed it will be adjusted to match the earliest possible sensor reading. If the endTime provided is after any sensors installed it will be adjusted to match the last possible sensor reading.

If the requested time period will produce a payload that exceeds the maximum it will behave in one of two ways:

If a downsampleRate has been provided an error will be returned to the client explaining the requested parameters will exceed the maximum.

If no downsampleRate is specified the server will calculate a downsampleRate based upon default sensor settings that results in a result set close to the maximum number of data points. If a sensor is reporting with a non-default period (due to setup or environmental conditions) the actual number of returned sensor readings may deviate from the stated maximum.

The response payload will contain both the data and a summary of the start and end dates, the returned item count and the downsampleRate used.

The expected number of sensor readings is based upon a sensor returning a reading every minute, resulting in 1440 sensor readings per 24 hour period.

Authorizations:
OAuth2
path Parameters
trapId
required
string <uuid>
Example: 65ebb46c-b0a0-11ea-b3de-0242ac130004
query Parameters
startTime
required
integer <int64> >= 0
Example: startTime=1591305631

The start time for the time series data. Inclusive. A UNIX timestamp, seconds from 1970-01-01.

endTime
integer <int64>
Example: endTime=1591305631

The end time for the time series data. Inclusive. A UNIX timestamp, seconds from 1970-01-01.

downsampleRate
integer <int32> > 0
Example: downsampleRate=300

The number of seconds for the downsample interval. (3600 = 1 hour).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "resultSetInfo": {
    }
}

get SAGE metadata for this trap

Retrieve the metadata for this trap held by SAGE. Note, this will only work for SAGE integrated traps.

Authorizations:
OAuth2
path Parameters
trapId
required
string <uuid>
Example: e5d80a07-7d04-4873-a5b8-169f4cb02962

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Webhook Subscriptions

Endpoints and components related to webhook subscriptions.

get webhook subscriptions

Get webhook subscriptons for the passed clientId.

Authorizations:
OAuth2
query Parameters
eventType
string
Enum: "machine-alarm-state-change-event" "trap-state-change-event"

Filter the list of webhook subscriptions by the type of event the subscription is notified about.

page
required
integer <int32> >= 1
Default: 1
Example: page=1

A one-based index for the first page number to return from a paginated call.

pageSize
integer <int32> >= 1
Default: 50
Example: pageSize=25

The maximum number of items to return per page.

sortBy
string
Enum: "createdAt" "customerName" "eventType"

Indicate what field should be used to sort the returned list of webhook subscriptions. If omitted the createdAt is used as the default sort by parameter.

sortDir
string
Enum: "asc" "desc"
Example: sortDir=asc

The direction to sort the list of results, ascending or descending.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paginationInfo": {
    }
}

create new webhook subscription

Create a new webhook subscription.

Authorizations:
OAuth2
Request Body schema: application/json

A webhook subscription to create or update.

eventType
required
string (WebhookEventTypeList)
Enum: "machine-alarm-state-change-event" "trap-state-change-event"

The type of event the AuthClient is subscribing to receive with the webhook.

webhookEndpoint
required
string

The endpoint the webhook service will post to.

webhookPassword
string

Auth password for partners.

webhookUsername
string

Auth username for partners.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete a webhook subscription by id

Delete a webhook subscription.

Authorizations:
OAuth2
path Parameters
webhookSubscriptionId
required
string <uuid>
Example: 16c09dab-49d3-4024-ac23-d55602771048

Responses

Response samples

Content type
application/json
Example
{
  • "code": "error_validation",
  • "message": "Validation error.",
  • "errors": [
    ]
}

get webhook subscription by id

Get webhook subscripton by id

Authorizations:
OAuth2
path Parameters
webhookSubscriptionId
required
string <uuid>
Example: 16c09dab-49d3-4024-ac23-d55602771048
query Parameters
includeSecret
boolean
Example: includeSecret=true

If set to true the webhook secret is included in the response.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update an existing webhook subscription

Update webhook subscripton by id. This endpoint does not change the webhookSecret value. It is to modify The event type, url or specific authentication required to successfully post events.

Authorizations:
OAuth2
path Parameters
webhookSubscriptionId
required
string <uuid>
Example: 16c09dab-49d3-4024-ac23-d55602771048
Request Body schema: application/json

A webhook subscription to create or update.

eventType
required
string (WebhookEventTypeList)
Enum: "machine-alarm-state-change-event" "trap-state-change-event"

The type of event the AuthClient is subscribing to receive with the webhook.

webhookEndpoint
required
string

The endpoint the webhook service will post to.

webhookPassword
string

Auth password for partners.

webhookUsername
string

Auth username for partners.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "data": {
    }
}