States

Read Last

GET https://interay.io/api/v1/states/read/last

Read last state(s)

type

object

properties

  • device

The device unique identifier. Device Unique ID / Device External key

type

string (UUID) / string

  • entity

The parent unique identifier. Product Unique ID / Location Unique ID / Device Unique ID

type

string (UUID)

Response

type

array

items

type

object

properties

  • channel

Product Unique ID, Channel External key and .desired / .reported

type

string

pattern

product_uid:external_key.(desired|reported) / product_uid:external_key.(lat|lon|alt|pdop|hdop|vdop|sats).(desired|reported)

  • value

State value

type

boolean / number / string

  • error

State error

type

number (POSIX error)

  • aggregated

State aggregation

enum

derivative.1s, derivative.1m, derivative.1h, last

  • entity

The device unique identifier. Device Unique ID

type

string (UUID)

  • timestamp

State date/time

type

number (Unix time)

Notes

  1. Request device and entity are mutually exclusive.

  2. Response value and error are mutually exclusive.

  3. Response timestamp is in decimal seconds with millisecond precision.

Example request

GET https://interay.io/api/v1/states/read/last?device=00000000-0000-0000-0000-000000000000
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example response

200 OK
Content-Type: application/json

[
        {
                "channel": "99999999-9999-9999-9999-999999999999:modbus_1.reported",
                "value": 1.0,
                "aggregated": "last",
                "entity": "00000000-0000-0000-0000-000000000000",
                "timestamp": 1767222000.001
        },
        {
                "channel": "99999999-9999-9999-9999-999999999999:modbus_2.reported",
                "error": -11,
                "aggregated": "last",
                "entity": "00000000-0000-0000-0000-000000000000",
                "timestamp": 1767222000.001
        }
]

Read History

GET https://interay.io/api/v1/states/read

Read state(s)

type

object

properties

  • devices

type

array

items

The device unique identifier. Device Unique ID / Device External key

type

string (UUID) / string

  • entities

type

array

items

The parent unique identifier. Product Unique ID / Location Unique ID / Device Unique ID

type

string (UUID)

  • channels

type

array

items

Channel External key and .desired / .reported

type

string

pattern

external_key.(desired|reported) / external_key.(lat|lon|alt|pdop|hdop|vdop|sats).(desired|reported)

  • timeRangeStart

The beginning of the queried time range

type

number (Unix time) / string (Duration) / string (ISO 8601)

  • timeRangeStop

The end of the queried time range

type

number (Unix time) / string (Duration) / string (ISO 8601)

  • windowPeriod

The period of aggregated data

type

number (seconds) / string (Duration)

Response

type

array

items

type

object

properties

  • channel

Product Unique ID, Channel External key and .desired / .reported

type

string

pattern

product_uid:external_key.(desired|reported) / product_uid:external_key.(lat|lon|alt|pdop|hdop|vdop|sats).(desired|reported)

  • value

State value

type

boolean / number / string

  • error

State error

type

number (POSIX error)

  • aggregated

State aggregation

enum

derivative.1s, derivative.1m, derivative.1h, last, max, mean, min

  • entity

The device unique identifier. Device Unique ID

type

string (UUID)

  • timestamp

State date/time

type

number (Unix time)

Notes

  1. Request devices and entities are mutually exclusive.

  2. Request timeRangeStart and timeRangeStop should have a negative Duration.

  3. Response value and error are mutually exclusive.

  4. Response timestamp is in decimal seconds with millisecond precision.

Example request

GET https://interay.io/api/v1/states/read?devices=00000000-0000-0000-0000-000000000000&timeRangeStart=-1d
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example response

200 OK
Content-Type: application/json

[
        {
                "channel": "99999999-9999-9999-9999-999999999999:modbus_1.reported",
                "value": 1.0,
                "aggregated": "last",
                "entity": "00000000-0000-0000-0000-000000000000",
                "timestamp": 1767222000.001
        },
        {
                "channel": "99999999-9999-9999-9999-999999999999:modbus_2.reported",
                "error": -11,
                "aggregated": "last",
                "entity": "00000000-0000-0000-0000-000000000000",
                "timestamp": 1767222000.001
        }
]

Write

POST https://interay.io/api/v1/states/write

Write state(s)

type

object

properties

  • device

The device unique identifier. Device Unique ID / Device External key

type

string (UUID) / string

  • states

The device state(s)

type

array

items

type

object

properties

  • channel

Channel External key and .desired / .reported

type

string

pattern

external_key.(desired|reported) / external_key.(lat|lon|alt|pdop|hdop|vdop|sats).(desired|reported)

  • value

State value

type

boolean / number / string

  • error

State error

type

number (POSIX error)

  • timestamp

State date/time

type

number (Unix time) / string (ISO 8601)

default

Server’s current time

Notes

  1. Request value and error are mutually exclusive.

  2. Request error is only allowed for .reported.

  3. Negative error values are displayed as POSIX errors descriptions.

Example request desired

POST https://interay.io/api/v1/states/write
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
        "device": "00000000-0000-0000-0000-000000000000",
        "states": [
                {
                        "channel": "modbus_1.desired",
                        "value": 1.0,
                },
                {
                        "channel": "modbus_2.desired",
                        "value": 2.0,
                }
        ]
}

Example response desired

200 OK

Example request reported

POST https://interay.io/api/v1/states/write
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
        "device": "00000000-0000-0000-0000-000000000000",
        "states": [
                {
                        "channel": "modbus_1.reported",
                        "value": 1.0,
                        "timestamp": "2019-09-26T07:58:30.996+0200",
                },
                {
                        "channel": "modbus_2.reported",
                        "error": -11,
                        "timestamp": "2019-09-26T07:58:30.996+0200",
                }
        ]
}

Example response reported

200 OK