Cloud API (75.0)

Welcome to the Cloud API reference.

Introduction

Cloud API is organized around the REST methodology, and it uses resource-oriented URLs, and common HTTP response codes to indicate API errors.

Authentication

Retrieve an access_token to authenticate yourself on the Core and Push API's.

Core

Core API fonctionnalities, avaliable on every plan and for every device types.

Push

Push API allows you to define 'callbacks' that are routing configurations for your device messages.

After defining a callback in IDIAG Push, all your device messages will be pushed to the defined callback route.

Access Token

OAuth2 - an open protocol to allow secure authorization in a simple and standard method from web, mobile and desktop applications.

All requests are authenticated using a JWT access_token (Json Web Token).

The access_token is retrieved from the authentication endpoint using your client-id and client-secret.

The client-id and client-secret can be retrieved from the Intesens Support Team.

How to use an access_token ?

The access_token must be placed in the Authorization Header with the authorization type Bearer.

How long can I use an access_token ?

The access_token expires after 24h (86400 seconds), you must reuse your token for several requests.

Retrieve an access token

Use this endpoint to directly request an Access Token by using the Client's credentials (a Client ID and a Client Secret).

Authorizations:
Request Body schema: application/json
grant_type
string
Value: "client_credentials"
client_id
string

Your application's Client ID.

client_secret
string

Your application's Client Secret.

audience
string
Value: "https://api.idiag.com"

The unique identifier of the target API you want to access.

Responses

200

successful authentication

post /oauth/token
https://api.idiag.com/oauth/token

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "grant_type": "client_credentials",
  • "client_id": "string",
  • "client_secret": "string",
  • "audience": "https://api.idiag.com"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "access_token": "eyJz93a...k4laUWw",
  • "token_type": "Bearer",
  • "expires_in": 86400
}

Device

Endpoints to know everything about your devices.

Here you can retrive the last values of your devices resources.

List your devices

Return the list of your devices

Authorizations:
access_token (read:devices)

Responses

200

successful operation

get /device-state/v1/devices
https://api.idiag.com/device-state/v1/devices

Request samples

Copy
curl -X GET \
  https://<api url>/device-state/v1/devices \
  -H 'Authorization: Bearer <your access_token>' \
  -H 'Content-Type: application/json'

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Find device by serialNumber

Return a single device

Authorizations:
access_token (read:devices)
path Parameters
serialNumber
required
string

Serial number of the device to return

Responses

200

successful operation

404

Device not found

get /device-state/v1/devices/{serialNumber}
https://api.idiag.com/device-state/v1/devices/{serialNumber}

Request samples

Copy
curl -X GET \
  https://<api url>/device-state/v1/devices/<serialNumber> \
  -H 'Authorization: Bearer <your api_token>' \
  -H 'Content-Type: application/json'

Response samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "serialNumber": "IBAT-123FFF",
  • "name": "Fridge 25",
  • "location":
    {
    },
  • "operator":
    {
    },
  • "status":
    {
    },
  • "state":
    {
    },
  • "deviceType": "Default"
}

Change a device location

Set location for a device.

Authorizations:
access_token (write:devices)
path Parameters
serialNumber
required
string

Serial number of the device to update

Request Body schema: application/json

The new location of the device

type
string
Value: "Point"
coordinates
Array of numbers

Array containing [latitude, longitude]

Responses

200

successful operation

404

Device not found

put /device-state/v1/devices/{serialNumber}/location
https://api.idiag.com/device-state/v1/devices/{serialNumber}/location

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "type": "Point",
  • "coordinates":
    [
    ]
}

Response samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "serialNumber": "IBAT-123FFF",
  • "name": "Fridge 25",
  • "location":
    {
    },
  • "operator":
    {
    },
  • "status":
    {
    },
  • "state":
    {
    },
  • "deviceType": "Default"
}

Change a device name

Set name for a device.

Authorizations:
access_token (write:devices)
path Parameters
serialNumber
required
string

Serial number of the device (re)name

Request Body schema: application/json

The new name of the device

string

Responses

200

successful operation

404

Device not found

put /device-state/v1/devices/{serialNumber}/name
https://api.idiag.com/device-state/v1/devices/{serialNumber}/name

Request samples

Content type
application/json
Copy
Expand all Collapse all
"Fridge 25"

Response samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "serialNumber": "IBAT-123FFF",
  • "name": "Fridge 25",
  • "location":
    {
    },
  • "operator":
    {
    },
  • "status":
    {
    },
  • "state":
    {
    },
  • "deviceType": "Default"
}

Configure a device

Set a target configuration for a device.

Two types of device can be configured :

Authorizations:
access_token (write:downlink)
path Parameters
serialNumber
required
string

Serial number of the device to configure

Request Body schema: application/json
deviceType
required
string
batteryChemistry
required
string
Enum: "LEAD" "MINH_MICD" "LI_ION" "LIFEPO4"

Chemistry of the battery.

nominalVoltage
required
number <double> [ 0 .. 110 ]

Nominal voltage of the battery.

minimalVoltage
required
number <double> [ 0 .. 110 ]

Minimal voltage of the battery.

isFloatingCharger
boolean

If the battery is plugged to a floating charger

resumptionVoltage
number <double> [ 0 .. 110 ]

If using a floating charger, the lower threshold voltage when the charge resume charging

watches
object (Configuration_IDIAG_Battery_v1-Watches)

Flags enabling or disabling alerts types on the device

Responses

202

successful operation

404

Device not found

post /device-state/v1/devices/{serialNumber}/configuration
https://api.idiag.com/device-state/v1/devices/{serialNumber}/configuration

Request samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "deviceType": "IDIAG_Battery_v1",
  • "minimalVoltage": 19,
  • "nominalVoltage": 101.5,
  • "batteryChemistry": "LEAD",
  • "isFloatingCharger": true,
  • "resumptionVoltage": 90,
  • "watches":
    {
    }
}

History

Endpoints to explore resources history.

History endpoints will allow you to retrieve data series that can be used to create timelines and graphs.

Retrieve resource series

Get data serie of a resource for a device

Authorizations:
access_token (read:history)
path Parameters
serialNumber
required
string

Serial number of the device to return

resourceName
required
string

Name of the resource to return

query Parameters
start
required
string <date-time> yyyy-MM-dd'T'HH:mm:ss.SSSZ

Start date-time of the wanted series

end
required
string <date-time> yyyy-MM-dd'T'HH:mm:ss.SSSZ

End date-time of the wanted series

page
integer <int32> >= 0
Default: 0

Requested page number

size
integer <int32> [ 0 .. 1000 ]