API Error Codes and Responses

200

OK

Success!

400

Bad Request

The request was invalid. An accompanying error message will explain further.

401

Unauthorized

Missing or invalid authentication credentials.

403

Forbidden

The request is understood, but it has been refused or access is not allowed. An accompanying error message will explain further.

406

Not Acceptable

Invalid accept type in header. Supported types are listed per route. All routes support application/json and historical data routes also support text/csv.

413

Request Entity Too Large

The response is too large. If making a request through an historical data route, try using a smaller Start and End date range.

500

Internal Server Error

An unexpected exception occurred. Contact support. Be sure to supply the x-logging-id in the response header.

100

Authentication credentials are missing or incorrect.

Corresponds with an HTTP 401.

201

Content type not supported.

Corresponds with an HTTP 406.

202

Unexpected exception.

Corresponds with an HTTP 500.

203

Requested payload is too large. Try limiting date range or number of tags in request.

Corresponds with an HTTP 413.

205

Unauthorized resource requested.

Corresponds with an HTTP 403.

1001

Empty list of tag ids presented during live data retrieval.

Corresponds with an HTTP 400. This will be returned if live data routes return no data.

1100

Missing required Tag Id.

Corresponds with an HTTP 400.

1101

Missing required start date.

Corresponds with an HTTP 400. Returned by the historical data routes when start date parameter is missing.

1103

Missing required end date.

Corresponds with an HTTP 400. Returned by the historical data routes when end date parameter is missing.

1105

Invalid end date. End date/time must be greater than start date/time.

Corresponds with an HTTP 400. Returned by the historical data routes when specified date range is invalid.

1106

Invalid interval. Supported values are Minute, QuarterHour, Hour or Day.

Corresponds with an HTTP 400. Returned by the historical data routes when the interval parameter contains a non-supported value.

1201

Missing required filter id.

Corresponds with an HTTP 400.

Id

String

Unique identifier for the filter.

Name

string

Name of the filter.

Tags

Array of Tag objects

Array of Tag objects

Tag:Id

String

Unique Identifier for tag.

Tag:Name

String

Name of the tag.

Tag:Entity

String

Name of entity associated to the tag.

Tag:SiteName

String

Name of site associated with entity, otherwise, empty string.

Tag:SiteId

String

Unique identifier for site associated with entity, otherwise an empty Globally Unique Identifier (GUID). For example, 00000000-0000-0000-0000-000000000000.

Tag:Building

String

Name of building associated with entity, otherwise, empty string.

Tag:Floor

String

Name of floor associated with entity, otherwise, empty string.

Tag:Room

String

Name of room associated with entity, otherwise, empty string.

Tag:DataType

String

Contains discrete or analog.

SiteId

String

Unique identifier for the site associated with the entity, otherwise, empty GUID. For example, 00000000-0000-0000-0000-000000000000.

SiteName

String

Can contain one of the following:

1. Name of the site associated with entity or empty string.

2. “Given tag is not authorized.” This occurs when authenticated user is not authorized to view the entity associated with tag.

TagId

String

Unique identifier for tag.

SiteDateTime

String

The date/time for data point expressed in the site time zone.

DateTimeUTC

String

Date/time for the data point expressed in UTC.

Mean

Number

The average value over the interval. For cumulative data, this will represent the delta over the interval.

Min

Number

Minimum value over interval.

Max

Number

Maximum value over interval.

Median

Number

Median value over interval.

Total

Number

Sample value at earliest time unit for sample, rather than the sum of the values over the interval of the sample.

StDev

Number

Standard deviation over interval.

SampleSize

Integer

Expected number of data points used to evaluate interval.

ActualSampleSize

Integer

Actual number of data points used to evaluate interval.

Quality integer

Integer

Not implemented.

MinTsUTC

String

Date/time Min value captured.

MaxTsUTC

String

Date/time Max value captured.

SampleTsUTC

String

Date/time the SampleValue was captured.

Sample

Number

The earliest value within the sample interval. For an interval of Minute this is the first (00) second, for all other intervals this is the first minute.

TimeStampUTC

String

The date/time in UTC corresponding to live value.

LiveData

Array of Tag/Value pairs

Array of Tag/Value pairs.

TagId

String

Unique identifier for tag.

Value

String

Can contain one of the following:

1. Live tag value.

2. “Given tag is not authorized.” Occurs when authenticated user is not authorized to view entity associated with tag.

3. “Given tag is invalid.” Occurs when not capturing data for the tag.

Status

String

HTTP status code for the response. See list of possible HTTP status codes.

Messages

Array of message objects

Array of message objects

Message:Message string

String

Description of error. See list of error messages and associated codes.

Message:ErrorCode

String

Code associated to the error.

insertType

String

Yes

Only supports ‘insertNew’ which means a new record will be added. If the record already exists, the data point will be ignored. May support updates in the future.

interval

String

Yes

Defines type of sample being posted. Supported values are minute, quarter-hour, hour and day.

timeZoneSource

String

Yes

Source of time zones for timestamps in the posted payload. Supported values are site and UTC. When set to UTC, there will be no conversion done on posted timestamps. When set to site, the time zone associated to the tag’s site will be used to convert the timestamp to UTC for persistence.

timeStamp

String

Yes

Timestamp for samples in the post. Can provide multiple timestamps/data points per payload.

tagId

String

Yes

Aurora internal identifier for data point.

value

String

Yes

Actual value for data point.

mean

String

Only when part of an aggregated sample

Average value for data point over an interval.

min

String

Only when part of an aggregated sample

Minimum value for data point over an interval.

max

String

Only when part of an aggregated sample

Maximum value for data point over an interval.

median

String

Only when part of an aggregated sample

Median value for data point over an interval.

stDev

String

Only when part of an aggregated sample

Standard deviation for data point over the interval.

sampleSize

Number

Only when part of an aggregated sample

Number of actual data points used to calculate aggregated values over the interval.

quality

Number

Only when part of an aggregated sample

If there were actual data points used to calculate the aggregated values, this should be set to 0. If only estimated data points were used, then set to 1.

minTimeStamp

String

Only when part of an aggregated sample

Timestamp associated with minimum value over the interval.

maxTimeStamp

String

Only when part of an aggregated sample

Timestamp associated with maximum value over the interval.

Id

String

Unique identifier for alarm instance.

AlarmType

String

Possible values: sys (for system), dig (for digital), hihi, hi, lolo, lo, run.

Tag

String

If alarm is on a specific tag, this is the tag name, otherwise, empty string.

TagId

String

If alarm is on a specific tag, this is the unique identifier for tag.

Description

String

Description of the alarm.

Value

String

Value that triggered the alarm.

CurrentValue

String

Current value for data point that triggered an alarm.

ValueFriendlyName

String

For alarms of type hihi, hi, lolo and lo. Distinct friendly names can be configured for alarms.

Status

String

Current state of the alarm. Possible values are: Cleared, Acknowledged, Unacknowledged.

SiteId

String

If related to a site, this is the unique identifier for site.

Site

String

If related to a site, this is the site name.

BuildingId

String

If related to an entity mapped to a building, this is the unique identifier for building.

Building

String

If related to an entity mapped to a building, this is the building name.

FloorId

String

If related to an entity mapped to a floor, this is the unique identifier for floor.

Floor

String

If related to an entity mapped to a floor, this is the floor name.

RoomId

String

If related to an entity mapped to a room, this is the unique identifier for room.

Room

String

If related to an entity mapped to a room, this is the room name.

EntityId

String

If related to an entity, this is the unique identifier for the entity.

Entity

String

If related to an entity, this is the entity name.

Device

String

If related to a device, this is the device name.

DateTimeInitiatedUtc

String

Date and time the alarm was initiated in UTC.

DateTimeAcknowledgedUtc

String

If acknowledged, this is the date and time the alarm was acknowledged in UTC.

DateTimeClearedUtc

String

If cleared, this is the date and time the alarm cleared in UTC.

UserAcknowledged

String

If acknowledged by a user, a userid will be indicated.

Url

String

URL to retrieve state of this alarm.