Embever IoT Core API

Authenticating ¶

The API uses JWT tokens to authorize requests to ressources. Your application can obtain an access token by posting an application token to the /authenticate endpoint (for creatinng application tokens refer to Tokens). The access token is used for the requests to the API, but has a short validity period. When it expires, the application token must be used again to gain a new auth token. The access token is passed in the request’s Authorization header.

Content-Type: application/json

{
  "application_token": "eyJ0eXAiOiJKv2QiLCJhbGciOiJIUzUxMi..."
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "application_token": {
      "type": "string"
    }
  },
  "required": [
    "application_token"
  ]
}

Content-Type: application/json

{
  "access": "eyJ0eXAiOiJKv2QiLCJhbGciOiJIUdUxMi...",
  "refresh": "eyJ0eXAiOiJKv2QiLCJhbGciOiJIUzUxMi..."
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "access": {
      "type": "string"
    },
    "refresh": {
      "type": "string"
    }
  }
}

Webhooks ¶

Embever IoT Core offers a webhook mechanism to inform other services about Events and changes in Action statuses.

Event Webhooks ¶

Event Webhooks are triggered when an Event object is created. Event Webhooks are defined per device and live in the device.webhooks attribute. They have the structure:

{
  "type": "event_type",
  "url": "https://mybackend.com/position/",
  "payload_only": false
}

The type indicates what Event type triggers the webhook. If an Event with type="foo" is received from a device, the system will look look up all webhooks type="foo" and process this hooks accordingly. The system will issue a POST request to the specified url. The body of that request contains the created Event instance (JSON encoded). The "payload_only" is a boolean attribute, is optional and defults to false. If "payload_only" is set to true, the body of POST contains only the value of "payload" attribute. Setting "payload_only" attribute may come handy when working with telemetry data.

Action Webhooks ¶

Action Webhooks are triggered when the status of an Action instance changes. Action Webhooks are defined per action and live in the action.webhooks attribute. They have the structure:

[
  {
    "url": "https://mybackend.com/status-update/",
    "status": "action_sent"
  },
  {
    "url": "https://mybackend.com/response/",
    "status": "response_received",
    "payload_only": true
  },
  ......
]

The "status" indicates which status type triggers the webhook. If an Action reaches the action_sent status, the system will look look up all webhooks withstatus="action_sent" and process this hooks accordingly. The system will issue a POST request to the specified url. The body of that request contains the updated Action instance (JSON encoded). The "payload_only" is a boolean attribute, is optional and defults to false. If "payload_only" is set to true, the body of POST contains only the value of "result" attribute of an Action.

Headers of the request ¶

To authenticate the request, the system will add the following headers to the request

• X-Org-Token

• X-App-Token if the corresponding device is attached to an application

X-Org-Tokenand X-App-Token are JWTs that are signed with the organisation.secret and application.secret respectively. The payload of the tokens have the following attributes:

• organisation_id or application_id

• iat - datetime at which the token was created

• exp - datetime at which the token expires. This is determined by the max_token_lifespan_in_seconds attribute.

Service Levels ¶

Embever IoT core supports three different Serivice Levels which determine the quality of service of the delivery of action to the device.

Service Level 0 ¶

When actions are created with service_level=0, Embever Cloud makes sure the actions are sent to the device but these actions are not guranteed to be delivered or to be processed by the device.

Service Level 1 ¶

When actions are created with service_level=1, Embever Cloud makes sure the actions are sent to the device and guranteed to be received by the device. These actions are not guranteed to be processed by the device. Embever Cloud will lock these actions until the device sends the acknowledgement of receiving the action. If not acknowledged by the device, Embever Cloud will resend the action. The sending of the action can be can be cancelled by setting the property cancelled to True.

Service Level 2 ¶

Actions created with service_level=2 are guranteed to be processed by the device. Embever Cloud makes sure that these actions are sent to the device, received and processed. Embever cloud will lock these actions unitil it receives the acknowledgement that the actions has been processed.

API Root ¶

Content-Type: application/json

{
  "devices": "https://api.embever.com/v2/devices/",
  "actions": "https://api.embever.com/v2/actions/",
  "events": "https://api.embever.com/v2/events/",
  "applications": "https://api.embever.com/v2/applications/",
  "firmwares": "https://api.embever.com/v2/firmwares/",
  "deployments": "https://api.embever.com/v2/deployments/",
  "updates": "https://api.embever.com/v2/updates/",
  "organisations": "https://api.embever.com/v2/organisations/",
  "tokens": "https://api.embever.com/v2/tokens/",
  "authenticate": "https://api.embever.com/v2/authenticate/"
}

Pagination ¶

Request that return multiple items will be paginated to 100 items by default. The api offers a way to easily navigate through the items using the ?limit and ?offset parameters. The ?limit parameter limits the number of results and the ?offset parameter skips the number of items before beginning to return the items. By default the the value of ?limit and ?offset is 100 and 0 respectively.

curl 'https://api.embever.com/v2/actions/?limit=100&offset=300'

Link Header ¶

The link header provides the information on pagination.

Link:
 <https://api.embever.com/v2/actions/?limit=100>; rel="first",
 <https://api.embever.com/v2/actions/?limit=100&offset=400>; rel="next",
 <https://api.embever.com/v2/actions/?limit=100&offset=200>; rel="previous",
 <https://api.embever.com/v2/actions/?limit=100&offset=578>; rel="last"

This Link response header contains one or more Hypermedia link relations. The possible rel values are:

Devices ¶

This section describes available API services for managing Devices.

Description of Devices ¶

A Device instance is representation of a single physical IoT device. Each physical device that you want to connect to Embever IoT Core needs its own Device instance.

Example Device object:

{
  "url": "https://api.embever.com/v2/devices/a1b2c3",
  "id": "a1b2c3",
  "name": "yourdevicename",
  "activated": false,
  "application": "6dbeb7f9-2d34-4411-9e34-9c7ae361cb92",
  "type": "other",
  "connectivity": {},
  "webhooks": [
    {
      "type": "position",
      "url": "https://mybackend.com/position/"
    },
    {
      "type": "temp",
      "url": "https://mybackend.com/temp/"
    },
    {
      "type": "temp",
      "url": "https://myotherbackend.com/temp/"
    }
  ],
  "created_at": "2018-02-26T16:02:13.978899Z"
}

(Un-)Linking an Application ¶

A Device can be linked to an Application in order to allow the Application to create Actions for this device. This is done by setting the "application" attribute to the ID of the Application instance. To release a Device from an Application, set the attribute to null.

SIM-based Devices ¶

If you want to connect SIM-based device, please contact us. SIM-based devices usually connect through a VPN to Embever IoT Core. SIM based devices have to be created by Embever.

Connecting Arbitrary Devices ¶

You can also create devices by yourself. Upon creating a device instance, you receive a password that is needed to authenticate the device against our public Gateway.

Webhooks ¶

The webhooks that are attached to a device are triggered when an Event with a matching type is received from the device. You can determine multiple hooks for the same type of event. After a webhook gets triggered, the created event object is send to the specified url using a POST request.

Content-Type: application/json

[
  {
    "url": "https://api.embever.com/v2/devices/a1b2c3",
    "id": "a1b2c3",
    "name": "yourdevicename",
    "activated": false,
    "application": "6dbeb7f9-2d34-4411-9e34-9c7ae361cb92",
    "type": "other",
    "connectivity": {},
    "webhooks": [
      {
        "type": "position",
        "url": "https://mybackend.com/position/"
      },
      {
        "type": "temp",
        "url": "https://mybackend.com/temp/"
      }
    ],
    "created_at": "2018-02-26T16:02:13.978899Z"
  }
]

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Content-Type: application/json

{
  "application": "6dbeb7f9-2d34-4411-9e34-9c7ae361cb92",
  "name": "somedevicename",
  "activated": true
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "application": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "activated": {
      "type": "boolean"
    }
  },
  "required": [
    "name"
  ]
}

Content-Type: application/json

{
  "url": "https://api.embever.com/v2/devices/a1b2c3",
  "id": "a1b2c3",
  "name": "yourdevicename",
  "activated": false,
  "application": "98hasdib",
  "type": "other",
  "connectivity": {},
  "webhooks": [
    {
      "type": "position",
      "url": "https://mybackend.com/position/"
    },
    {
      "type": "temp",
      "url": "https://mybackend.com/temp/"
    }
  ],
  "created_at": "2018-02-26T16:02:13.978899Z",
  "password": "somerandompassword"
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "activated": {
      "type": "boolean"
    },
    "application": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "connectivity": {
      "type": "object"
    },
    "webhooks": {
      "type": "array"
    },
    "created_at": {
      "type": "string"
    },
    "password": {
      "type": "string"
    }
  },
  "required": [
    "password"
  ]
}

Content-Type: application/json

{
  "url": "https://api.embever.com/v2/devices/a1b2c3",
  "id": "a1b2c3",
  "name": "yourdevicename",
  "activated": false,
  "application": "6dbeb7f9-2d34-4411-9e34-9c7ae361cb92",
  "type": "other",
  "connectivity": {},
  "webhooks": [
    {
      "type": "position",
      "url": "https://mybackend.com/position/"
    },
    {
      "type": "temp",
      "url": "https://mybackend.com/temp/"
    }
  ],
  "created_at": "2018-02-26T16:02:13.978899Z"
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "activated": {
      "type": "boolean"
    },
    "application": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "connectivity": {
      "type": "object"
    },
    "webhooks": {
      "type": "array"
    },
    "created_at": {
      "type": "string"
    }
  }
}

Content-Type: application/json

{
  "application": "98hasdib",
  "name": "newname",
  "activated": true
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "application": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "activated": {
      "type": "boolean"
    }
  }
}

Content-Type: application/json

{
  "url": "https://api.embever.com/v2/devices/a1b2c3",
  "id": "a1b2c3",
  "name": "newname",
  "activated": false,
  "application": "98hasdib",
  "type": "other",
  "connectivity": {},
  "webhooks": [
    {
      "type": "position",
      "url": "https://mybackend.com/position/"
    },
    {
      "type": "temp",
      "url": "https://mybackend.com/temp/"
    }
  ],
  "created_at": "2018-02-26T16:02:13.978899Z"
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "activated": {
      "type": "boolean"
    },
    "application": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "connectivity": {
      "type": "object"
    },
    "webhooks": {
      "type": "array"
    },
    "created_at": {
      "type": "string"
    }
  }
}

Content-Type: application/json

Applications ¶

This section available API operations to manage Applications.

Description of Applications ¶

An Application represents a group of devices. Each device can be (but doesn’t have to be) assigned to an Application. Each Application can manage Actions for Device instances that are assigned to this particular Action. You can create Application Token to authorize an Application against the API (Read the Tokens section and Authenticating section for more info). This way you can restrict access for an Application or customer group to a specific set of devices.

Example Application instance:

{
  "url": "https://api.embever.com/v2/devices/dbeb7f9-2d34-4411-9e34-9c7ae361cb92/",
  "id": "6dbeb7f9-2d34-4411-9e34-9c7ae361cb92",
  "alias": "testapp",
  "description": "Some description",
  "created_at": "2018-02-26T16:02:13.978899Z"
}

Assigning Devices to Applications ¶

Please refer to the Devices section.

Content-Type: application/json

[
  {
    "url": "https://api.embever.com/v2/devices/dbeb7f9-2d34-4411-9e34-9c7ae361cb92/",
    "id": "6dbeb7f9-2d34-4411-9e34-9c7ae361cb92",
    "alias": "testapp",
    "description": "Some description",
    "created_at": "2018-02-26T16:02:13.978899Z"
  }
]

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Content-Type: application/json

{
  "alias": "App1",
  "description": "some description",
  "secret": "top-secret"
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "alias": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "secret": {
      "type": "string"
    }
  },
  "required": [
    "alias",
    "secret"
  ]
}

Content-Type: application/json

{
  "url": "https://api.embever.com/v2/devices/dbeb7f9-2d34-4411-9e34-9c7ae361cb92/",
  "id": "6dbeb7f9-2d34-4411-9e34-9c7ae361cb92",
  "alias": "testapp",
  "description": "Some description",
  "created_at": "2018-02-26T16:02:13.978899Z"
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "alias": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "created_at": {
      "type": "string"
    }
  }
}

Content-Type: application/json

{
  "url": "https://api.embever.com/v2/devices/dbeb7f9-2d34-4411-9e34-9c7ae361cb92/",
  "id": "6dbeb7f9-2d34-4411-9e34-9c7ae361cb92",
  "alias": "testapp",
  "description": "Some description",
  "created_at": "2018-02-26T16:02:13.978899Z"
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "alias": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "created_at": {
      "type": "string"
    }
  }
}

Content-Type: application/json

{
  "alias": "App1",
  "description": "some description",
  "secret": "top-secret"
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "alias": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "secret": {
      "type": "string"
    }
  },
  "required": [
    "alias",
    "secret"
  ]
}

Content-Type: application/json

{
  "url": "https://api.embever.com/v2/devices/dbeb7f9-2d34-4411-9e34-9c7ae361cb92/",
  "id": "6dbeb7f9-2d34-4411-9e34-9c7ae361cb92",
  "alias": "testapp",
  "description": "Some description",
  "created_at": "2018-02-26T16:02:13.978899Z"
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "alias": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "created_at": {
      "type": "string"
    }
  }
}

Content-Type: application/json

Actions ¶

This section describes available API services for managing Action resources.

Description of Actions ¶

Actions are atomic operations or instructions that are sent to the device upon wake up. Each Action object is of a specific type and might have additional information (payload) that shall be sent to the device, e.g. some settings or other information that is needed to process the action.

Example Action object:

{
  "url": "https://api.embever.com/v2/actions/62542",
  "id": 62542,
  "device": {
    "id":"8112635472",
    "name": "XY2009"
  },
  "type": "setSettings",
  "payload": {
    "someSetting": 54
  },
  "webhooks": [
    {
      "status": "action_sent",
      "url": "https://mybackend.com/action_sent/"
    },
    {
      "status": "action_overridden",
      "url": "https://mybackend.com/action_overridden/"
    },
    {
      "status": "response_received",
      "url": "https://mybackend.com/response/"
    }
  ],
  "status": {
    "action_sent": "2018-02-27T18:02:13.978899Z"
  },
  "service_level": 0,
  "cancelled": false,
  "finished": true,
  "result": {
    "success":{
      "someSetting":54
    }
  },
  "created_at": "2018-02-26T16:02:13.978899Z",
  "result_code": "Success",
  "expiry_date": "2018-03-26T17:02:13Z",
  "expired": false
}

Buffering Actions ¶

Actions can be created at any time. However, they cannot be sent to sleeping devices. Therefore, Embever IoT Core keeps a set of Action objects in a buffer. Actions in the Buffer will be sent to the device upon its next wakeup. All of this magic happens automatically. You don’t have to do anything special here. However, it is important to note, that at maximum one Action of a particular type is kept in the buffer.

Action types ¶

The type attribute of an Action can principally be choosen by the user. It is the responsibility of the developer to implement the corresponding action handlers in the device’s firmware. The value of the type attribute must not start with "_", since these action types are private (can only be set by Embever IoT Core).

Embever IoT Core has some predefined action types, of which some some are private, i.e. can not be created by the user.

Public occupied types ¶

Example getFile Action request object:

{
    "device": {
      "id": "SB8rywL"
    },
    "type": "getFile",
    "payload": {
      "file": "data:image/epd;base64,aGVsbG93b3JsZA=="
    }
}

Example corresponding getFile Action response object:

{
    "url": "https://api.embever.com/v2/actions/28/",
    "id": 28,
    "device": {
        "id": "SB8rywL",
        "name": "dev_emb"
    },
    "type": "getFile",
    "payload": {
        "file": "rULZsHiM"
    },
    "webhooks": null,
    "status": null,
    "service_level": 0,
    "cancelled": false,
    "finished": false,
    "result": null,
    "created_at": "2020-01-15T12:38:39.277934Z",
    "result_code": null,
    "expiry_date": null,
    "expired": false
}

Private types ¶

Action status ¶

The status of an Action changes over its lifecycle. The status attribute of an Action is an object that can contain the following attributes

Actions of type:getFile and type:_fota can have additional statuses

The value of each attribute of a status object is a string indicating the time that status was reached. Example

{
  "action_sent": "2018-02-26T18:02:03.978399Z",
  "action_delivered": "2018-02-26T18:05:03.978399Z",
  "response_received": "2018-02-26T18:07:03.128399Z",
}

Responses ¶

If a response message is received from the device, its corresponding action will be updated. That is, a

1. Its attribute finished will be set to true
2. The payload of the response message will be added to the result attribute of the Action
3. The corresponding response_received webhook will be executed

The finished attribute ¶

Whether an Action instance is considered finished depends on status of the delivery of the action. If the achieved service level is equal to or higher than the service level indicated in service_level attribute, the action is considered to be finished. Service Level 0 is the lowest and Service Level 2 is the highest. For example, if the action with service_level=0 reaches the service level 0 or 1 or 2, the action is considered to be finished.

1. If the action is overridden

The finished attribute is set to true as soon as the action status action_overridden is reached.

2. If cancelled=true

   The finished attribute is set to true as soon as the cancelled attribute is set to true.

3. If the achieved service_level is equal to or higher than the action’s service_level attribute.

   For service_level=0, finished attribute is set to true as soon as the action status action_sent or action_delivered or response_received is reached.

   For service_level=1, finished attribute is set to true as soon as the action status action_delivered or response_received is reached.

   For service_level=2, finished attribute is set to true as soon as the action status response_received is reached.

Webhooks ¶

The webhooks that are attached to an action are triggered when the status of an Action is updated. The status attribute of the webhook specifies which statuses trigger the webhook. You can determine multiple hooks for the same status of the action. After a webhook gets triggered, the created updated status object is send to the specified url using a POST request.

The cancelled Attribute ¶

This field is primarily used to stop the action from sending to the device. Infact, this is the only field you can update in an Action. Suppose you create an Action (with id 001)of type “getTemp” with service level 2. The action is sent but the response is not received. For some reasons, if the action is not finished (response is not received) then it is sent again and again until the response is received. This action (with id 001) is a blocking action. No action of same type “getTemp” can be sent unless this action is finished. So if you want to send a new action (id 002) of the same type “getTemp”, you won’t be able to send it. To avoid this problem, one can update the "cancelled" attribute of Action (001) to true. This will allow the next action (002) to be sent to the device.

Expiry of Actions ¶

An action can be set to expire by setting the "expiry_date" attribute. After the set timestamp is reached, the action cannot be send to the device and the "expired" attribute is set to true. If the action is sent before the "expiry_date" the "expired" attribute is set to false.

Result Code of Actions ¶

When a response message is received from the device, the result code of the corresponding action is set to either Success or Failure, indicating whether the Action could be executed without errors in the IoT device.

Content-Type: application/json

[
  {
    "url": "https://api.embever.com/v2/actions/62542",
    "id": 62542,
    "device": {
      "id": "a1b2c3",
      "name": "yourdevicename"
    },
    "type": "setSettings",
    "payload": {
      "someData": 54
    },
    "webhooks": [
      {
        "status": "action_sent",
        "url": "https://mybackend.com/action_sent/"
      },
      {
        "status": "action_overridden",
        "url": "https://mybackend.com/action_overridden/"
      },
      {
        "status": "response_received",
        "url": "https://mybackend.com/response/"
      },
      {
        "status": "action_delivered",
        "url": "https://mybackend.com/action_delivered/"
      }
    ],
    "status": {
      "action_sent": "2018-02-27T16:02:13.978899Z",
      "action_overridden": "2018-02-27T16:02:15.978899Z",
      "response_received": "2018-02-27T16:02:15.978899Z"
    },
    "service_level": 0,
    "cancelled": false,
    "finished": true,
    "result": {},
    "created_at": "2018-02-26T16:02:13.978899Z",
    "result_code": "Success",
    "expiry_date": "2019-03-27T16:02:13Z",
    "expired": "false"
  }
]

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Content-Type: application/json

{
  "device": {
    "id": "a1b2c3",
    "name": "yourdevicename"
  },
  "type": "setSettings",
  "payload": {
    "someData": 54
  },
  "webhooks": [
    {
      "status": "action_sent",
      "url": "https://mybackend.com/action_sent/"
    },
    {
      "status": "action_overridden",
      "url": "https://mybackend.com/action_overridden/"
    },
    {
      "status": "response_received",
      "url": "https://mybackend.com/response/"
    }
  ]
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "device": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "type": {
      "type": "string"
    },
    "payload": {
      "type": "object",
      "properties": {
        "someData": {
          "type": "number"
        }
      }
    },
    "webhooks": {
      "type": "array"
    },
    "service_level": {
      "type": "number"
    },
    "cancelled": {
      "type": "boolean"
    }
  },
  "required": [
    "device",
    "type"
  ]
}

Content-Type: application/json

{
  "url": "https://api.embever.com/v2/actions/62542",
  "id": 62542,
  "device": {
    "id": "a1b2c3",
    "name": "yourdevicename"
  },
  "type": "setSettings",
  "payload": {
    "someData": 54
  },
  "webhooks": [
    {
      "status": "action_sent",
      "url": "https://mybackend.com/action_sent/"
    },
    {
      "status": "action_overridden",
      "url": "https://mybackend.com/action_overridden/"
    },
    {
      "status": "response_received",
      "url": "https://mybackend.com/response/"
    },
    {
      "status": "action_delivered",
      "url": "https://mybackend.com/action_delivered/"
    }
  ],
  "status": {
    "action_sent": "2018-02-27T16:02:13.978899Z",
    "action_overridden": "2018-02-27T16:02:15.978899Z",
    "response_received": "2018-02-27T16:02:15.978899Z"
  },
  "service_level": 0,
  "cancelled": false,
  "finished": true,
  "result": {},
  "created_at": "2018-02-26T16:02:13.978899Z",
  "result_code": "Success",
  "expiry_date": "2019-03-27T16:02:13Z",
  "expired": "false"
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "id": {
      "type": "number"
    },
    "device": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "type": {
      "type": "string"
    },
    "payload": {
      "type": "object",
      "properties": {
        "someData": {
          "type": "number"
        }
      }
    },
    "webhooks": {
      "type": "array"
    },
    "status": {
      "type": "object",
      "properties": {
        "action_sent": {
          "type": "string"
        },
        "action_overridden": {
          "type": "string"
        },
        "response_received": {
          "type": "string"
        }
      }
    },
    "service_level": {
      "type": "number"
    },
    "cancelled": {
      "type": "boolean"
    },
    "finished": {
      "type": "boolean"
    },
    "result": {
      "type": "object"
    },
    "created_at": {
      "type": "string"
    },
    "result_code": {
      "type": "string"
    },
    "expiry_date": {
      "type": "string"
    },
    "expired": {
      "type": "string"
    }
  }
}

Content-Type: application/json

{
  "url": "https://api.embever.com/v2/actions/62542",
  "id": 62542,
  "device": {
    "id": "a1b2c3",
    "name": "yourdevicename"
  },
  "type": "setSettings",
  "payload": {
    "someData": 54
  },
  "webhooks": [
    {
      "status": "action_sent",
      "url": "https://mybackend.com/action_sent/"
    },
    {
      "status": "action_overridden",
      "url": "https://mybackend.com/action_overridden/"
    },
    {
      "status": "response_received",
      "url": "https://mybackend.com/response/"
    },
    {
      "status": "action_delivered",
      "url": "https://mybackend.com/action_delivered/"
    }
  ],
  "status": {
    "action_sent": "2018-02-27T16:02:13.978899Z",
    "action_overridden": "2018-02-27T16:02:15.978899Z",
    "response_received": "2018-02-27T16:02:15.978899Z"
  },
  "service_level": 0,
  "cancelled": false,
  "finished": true,
  "result": {},
  "created_at": "2018-02-26T16:02:13.978899Z",
  "result_code": "Success",
  "expiry_date": "2019-03-27T16:02:13Z",
  "expired": "false"
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "id": {
      "type": "number"
    },
    "device": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "type": {
      "type": "string"
    },
    "payload": {
      "type": "object",
      "properties": {
        "someData": {
          "type": "number"
        }
      }
    },
    "webhooks": {
      "type": "array"
    },
    "status": {
      "type": "object",
      "properties": {
        "action_sent": {
          "type": "string"
        },
        "action_overridden": {
          "type": "string"
        },
        "response_received": {
          "type": "string"
        }
      }
    },
    "service_level": {
      "type": "number"
    },
    "cancelled": {
      "type": "boolean"
    },
    "finished": {
      "type": "boolean"
    },
    "result": {
      "type": "object"
    },
    "created_at": {
      "type": "string"
    },
    "result_code": {
      "type": "string"
    },
    "expiry_date": {
      "type": "string"
    },
    "expired": {
      "type": "string"
    }
  }
}

Events ¶

This section describes available API services for managing Event ressources.

Description of Events ¶

Events are representations of data that was sent from a device to Embever IoT Core. An Event is not a response to an Action. Rather, some condition in the device triggered the transmission of that data. Each Event object is of a specific type and might have additional information (payload) that was sent by the device, e.g. some sensor value or other information.

Example Event object:

{
  "url": "https://api.embever.com/v2/events/12",
  "id": 12,
  "device": "8112635472",
  "type": "battery_report",
  "payload": {
    "capacity": 73
  },
  "created_at": "2018-02-26T16:02:13.978899Z"
}

Webhooks ¶

Please refer to Device’s Webhooks section

Content-Type: application/json

[
  {
    "url": "https://api.embever.com/v2/actions/12",
    "id": 12,
    "device": "8112635472",
    "type": "someEventType",
    "payload": {
      "someData": 54
    },
    "created_at": "2018-02-26T16:02:13.978899Z"
  }
]

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Content-Type: application/json

{
  "url": "https://api.embever.com/v2/actions/12",
  "id": 12,
  "device": "8112635472",
  "type": "someEventType",
  "payload": {
    "someData": 54
  },
  "created_at": "2018-02-26T16:02:13.978899Z"
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "id": {
      "type": "number"
    },
    "device": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "payload": {
      "type": "object",
      "properties": {
        "someData": {
          "type": "number"
        }
      }
    },
    "created_at": {
      "type": "string"
    }
  }
}

Organisation ¶

This section describes available API services for managing Organisation ressources.

Description of Organisation ¶

An Organisation represents the parent entity which owns applications, devices and firmwares.

Example Organisation object:

{
    "url": "https://api.embever.com/v2/organisations/59662055-8395-4242-92fc-6809d2de7159",
    "id": "59662055-8395-4242-92fc-6809d2de7159",
    "name": "Embever",
    "street": "Carl-Miller Str.",
    "street_number": "6",
    "postal_code": "39112",
    "city": "Magdeburg",
    "country": "DE",
    "max_token_lifespan_in_seconds": 300,
    "created_at": "2019-09-16T12:49:44.152794Z"
}

Content-Type: application/json

[
  {
    "url": "https://api.embever.com/v2/organisations/7a2e64a2-9e85-4a75-9d63-f7060e63e0ce",
    "id": "7a2e64a2-9e85-4a75-9d63-f7060e63e0ce",
    "name": "Company Inc.",
    "street": "Sample-Str.",
    "street_number": "16",
    "postal_code": 39112,
    "city": "Remscheid",
    "country": "Germany",
    "max_token_lifespan_in_seconds": 300,
    "created_at": "2018-02-26T16:02:13.978899Z"
  }
]

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Content-Type: application/detail

Content-Type: application/json

{
  "secret": "updated_secret",
  "max_token_lifespan_in_seconds": 360
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "secret": {
      "type": "string"
    },
    "max_token_lifespan_in_seconds": {
      "type": "number"
    }
  }
}

Content-Type: application/json

{
  "url": "https://api.embever.com/v2/organisations/7a2e64a2-9e85-4a75-9d63-f7060e63e0ce",
  "id": "7a2e64a2-9e85-4a75-9d63-f7060e63e0ce",
  "name": "Company Inc.",
  "street": "Sample-Str.",
  "street_number": "16",
  "postal_code": 39112,
  "city": "Remscheid",
  "country": "Germany",
  "max_token_lifespan_in_seconds": 360,
  "created_at": "2018-02-26T16:02:13.978899Z",
  "secret": "updated_secret"
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "street": {
      "type": "string"
    },
    "street_number": {
      "type": "string"
    },
    "postal_code": {
      "type": "number"
    },
    "city": {
      "type": "string"
    },
    "country": {
      "type": "string"
    },
    "max_token_lifespan_in_seconds": {
      "type": "number"
    },
    "created_at": {
      "type": "string"
    },
    "secret": {
      "type": "string"
    }
  }
}

Tokens ¶

This section describes available API services for managing Token ressources.

Description of Token ¶

A Token is a unique string which contains credentials to identify the user. This vlaue of token attribute of a token object is used to generate access token from /authenticate endpoint point. The attribute token is retrieved only during token creation and has to be kept secret.

Example Token object:

{
    "id": 37,
    "url": "https://api.embever.com/v2/tokens/37/",
    "alias": "org_userf",
    "activated": true,
    "expiry_date": null,
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJhbGlhcyI6Im9yZ191c2VyZiIsInVzZXJfaWQiOjN9.dytQivqGZwNhtHvNFjziR0fzeBsWvHtQJgoQwhvZxHh2y4H_gww-KBTr8PHOd6jrJjiBV27GZcxGmJ-0QKzs5A",
    "scope": {
        "organisation": "59662055-8395-4242-92fc-6809d2de7159",
        "application": null,
        "user": 3
    },
    "created_at": "2020-02-05T12:58:18.202698Z"
}

Scope of Token ¶

The scope object shows the extend to which the token is confined to access the resources in the api. The scope attribute contains the following attributes

Content-Type: application/json

[
  {
    "url": "https://api.embever.com/tokens/15/",
    "id": 15,
    "alias": "sometoken",
    "activated": true,
    "expiry_date": "2018-02-26T16:02:13.978899Z",
    "scope": {
      "organisation": "7dbeb7f9-2d34-4411-9e34-9c7ae361cb92",
      "application": "6dbeb7f9-2d34-4411-9e34-9c7ae361cb92",
      "user": 5
    },
    "created_at": "2018-02-26T16:02:13.978899Z"
  }
]

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Content-Type: application/json

{
  "alias": "sometoken",
  "organisation": "7dbeb7f9-2d34-4411-9e34-9c7ae361cb92",
  "application": "6dbeb7f9-2d34-4411-9e34-9c7ae361cb92",
  "expiry_date": "2018-02-26T16:02:13.978899Z"
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "alias": {
      "type": "string"
    },
    "organisation": {
      "type": "string"
    },
    "application": {
      "type": "string"
    },
    "expiry_date": {
      "type": "string"
    }
  }
}

Content-Type: application/json

{
  "url": "https://api.embever.com/tokens/15/",
  "id": 16,
  "alias": "sometoken",
  "activated": true,
  "expiry_date": "2018-02-26T16:02:13.978899Z",
  "scope": {
    "organisation": "7dbeb7f9-2d34-4411-9e34-9c7ae361cb92",
    "application": "6dbeb7f9-2d34-4411-9e34-9c7ae361cb92",
    "user": 5
  },
  "created_at": "2018-01-26T16:02:13.978899Z",
  "token": "eyJ0eXAiOiJKv2QiLCJhbGciOiJIUzUxMiJ9.eyJhbGlhcyI6Ijhhc2RvdW5hc2QiLCJvcmdhbmlzYXRpb25faWQiOiI3YTJlNjRhMi05ZTg1LTRhNzUtOWQ2My1mNzA2MGU2M2UwY2UifQ.fFfZoEz60FdCDIi_oCKbxnke25jV5lVsB65cQ9eqh3v-xwMKqtTkvRdfa2yuQbLt9QsmIuMp14Gkxp61yThZhg"
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "id": {
      "type": "number"
    },
    "alias": {
      "type": "string"
    },
    "activated": {
      "type": "boolean"
    },
    "expiry_date": {
      "type": "string"
    },
    "scope": {
      "type": "object",
      "properties": {
        "organisation": {
          "type": "string"
        },
        "application": {
          "type": "string"
        },
        "user": {
          "type": "number"
        }
      }
    },
    "created_at": {
      "type": "string"
    },
    "token": {
      "type": "string"
    }
  }
}

Content-Type: application/json

{
  "url": "https://api.embever.com/tokens/15/",
  "id": 15,
  "alias": "sometoken",
  "activated": true,
  "expiry_date": "2018-02-26T16:02:13.978899Z",
  "scope": {
    "organisation": "7dbeb7f9-2d34-4411-9e34-9c7ae361cb92",
    "application": "6dbeb7f9-2d34-4411-9e34-9c7ae361cb92",
    "user": 5
  },
  "created_at": "2018-02-26T16:02:13.978899Z"
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "id": {
      "type": "number"
    },
    "alias": {
      "type": "string"
    },
    "activated": {
      "type": "boolean"
    },
    "expiry_date": {
      "type": "string"
    },
    "scope": {
      "type": "object",
      "properties": {
        "organisation": {
          "type": "string"
        },
        "application": {
          "type": "string"
        },
        "user": {
          "type": "number"
        }
      }
    },
    "created_at": {
      "type": "string"
    }
  }
}

Content-Type: application/json

Firmware ¶

Description of Firmware ¶

A Firmware object represents the firmware used in the device.

Example Firmware object:

{
    "url": "https://api.embever.com/v2/firmwares/UBNY6l/",
    "id": "UBNY6l",
    "version": "v1.0.0",
    "alias": "hg",
    "dest": "APP",
    "description": "",
    "predecessor": null,
    "created_at": "2019-11-01T08:51:04.756688Z"
}

Content-Type: application/json

[
  {
    "url": "https://api.embever.com/v2/firmwares/UBNY6l/",
    "id": "UBNY6l",
    "version": "1.0",
    "alias": "somefw",
    "dest": "EBV",
    "description": "some description",
    "predecessor": "au8auS",
    "created_at": "2018-02-26T16:02:13.978899Z"
  }
]

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Content-Type: application/json

{
  "version": "1.0",
  "alias": "somefw",
  "dest": "\"EBV\"",
  "description": "some description",
  "predecessor": "au8auS"
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "version": {
      "type": "string"
    },
    "alias": {
      "type": "string"
    },
    "dest": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "predecessor": {
      "type": "string"
    }
  },
  "required": [
    "version",
    "alias",
    "dest"
  ]
}

Content-Type: application/json

{
  "url": "https://api.embever.com/v2/firmwares/UBNY6l/",
  "id": "UBNY6l",
  "version": "1.0",
  "alias": "somefw",
  "dest": "EBV",
  "description": "some description",
  "predecessor": "au8auS",
  "created_at": "2018-02-26T16:02:13.978899Z"
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "version": {
      "type": "string"
    },
    "alias": {
      "type": "string"
    },
    "dest": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "predecessor": {
      "type": "string"
    },
    "created_at": {
      "type": "string"
    }
  }
}

Firmware Updates ¶

This section describes tha API operations to conduct firmware updates.

How Firmware Updates Work ¶

Embever IoT Core offers the ability to easily update your device’s firmware over the air. To initialize a firmware update you need to create a Deployment instance, referencing:

1. the Firmware instance that should be deployed (refer to the Firmware section)
2. the devices which should update to the new firmware.

This way, You can initialize firmware updates for several devices at once. We highly recommend to start with a test Deployment. That is, referencing some devices that you have physical control of to check whether the new firmware does work properly.

After you created the deployment, Embever IoT Core will automatically generate an _fota-type Action instance for each of your devices (please refer to the Actions section for more info about Actions). This Action will then be scheduled for delivery. Upon the device’s next wakeup it will receive this Action and proceed to download the correct firmware binary using our File Transfer Service. After the Update is complete, the device will send a response message and the corresponding Action, Update andDeployment instances will be updated accordingly.

Description of Deployments ¶

A Deployment is an aggregation of firmware update operations.

Example Deployment:

{
  "url": "https://api.embever.com/v2/deployments/15/",
  "id": 15,
  "devices": [
    "m8uGz",
    "a1b2c3"
  ],
  "successful":["m8uGz"],
  "pending": ["a1b2c3"],
  "failed": [],
  "firmware": "UBNY6l",
  "finished": false,
  "created_at": "2018-02-26T16:02:13.978899Z"
}

Content-Type: application/json

[
  {
    "url": "https://api.embever.com/v2/deployments/15/",
    "id": 15,
    "devices": [
      "m8uGz",
      "a1b2c3",
      "s4U9j0",
      "aN901x"
    ],
    "successful": [
      "m8uGz",
      "a1b2c3"
    ],
    "pending": [
      "s4U9j0"
    ],
    "failed": [
      "aN901x"
    ],
    "firmware": "UBNY6l",
    "finished": false,
    "created_at": "2018-02-26T16:02:13.978899Z"
  }
]

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Content-Type: application/json

{
  "devices": [
    "m8uGz",
    "a1b2c3"
  ],
  "firmware": "UBNY6l"
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "devices": {
      "type": "array"
    },
    "firmware": {
      "type": "string"
    }
  },
  "required": [
    "devices",
    "firmware"
  ]
}

Content-Type: application/json

{
  "url": "https://api.embever.com/v2/deployments/15/",
  "id": 15,
  "devices": [
    "m8uGz",
    "a1b2c3"
  ],
  "successful": [],
  "pending": [],
  "failed": [],
  "firmware": "UBNY6l",
  "finished": false,
  "created_at": "2018-02-26T16:02:13.978899Z"
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "id": {
      "type": "number"
    },
    "devices": {
      "type": "array"
    },
    "successful": {
      "type": "array"
    },
    "pending": {
      "type": "array"
    },
    "failed": {
      "type": "array"
    },
    "firmware": {
      "type": "string"
    },
    "finished": {
      "type": "boolean"
    },
    "created_at": {
      "type": "string"
    }
  }
}

Content-Type: application/json

{
  "url": "https://api.embever.com/v2/deployments/15/",
  "id": 15,
  "devices": [
    "m8uGz",
    "a1b2c3",
    "s4U9j0",
    "aN901x"
  ],
  "successful": [
    "m8uGz",
    "a1b2c3"
  ],
  "pending": [
    "s4U9j0"
  ],
  "failed": [
    "aN901x"
  ],
  "firmware": "UBNY6l",
  "finished": false,
  "created_at": "2018-02-26T16:02:13.978899Z"
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "id": {
      "type": "number"
    },
    "devices": {
      "type": "array"
    },
    "successful": {
      "type": "array"
    },
    "pending": {
      "type": "array"
    },
    "failed": {
      "type": "array"
    },
    "firmware": {
      "type": "string"
    },
    "finished": {
      "type": "boolean"
    },
    "created_at": {
      "type": "string"
    }
  }
}

Content-Type: application/json

[
  {
    "url": "https//api.embever.com/v2/updates/23/",
    "id": 23,
    "deployment": 15,
    "device": "m8uGz",
    "status": {
      "action_sent": "2018-02-27T16:02:13.978899Z",
      "response_received": "2018-02-27T16:05:15.978Z"
    },
    "result": {
      "status": 200
    },
    "result_code": "Success",
    "finished": true,
    "changed_at": "2018-02-26T16:02:13.978899Z",
    "created_at": "2018-02-26T16:02:13.978899Z"
  }
]

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Content-Type: application/json

{
  "url": "https//api.embever.com/v2/updates/23/",
  "id": 23,
  "deployment": 15,
  "device": "m8uGz",
  "status": {
    "action_sent": "2018-02-27T16:02:13.978899Z",
    "response_received": "2018-02-27T16:05:15.978Z"
  },
  "result": {
    "status": 200
  },
  "result_code": "Success",
  "finished": true,
  "changed_at": "2018-02-26T16:02:13.978899Z",
  "created_at": "2018-02-26T16:02:13.978899Z"
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "id": {
      "type": "number"
    },
    "deployment": {
      "type": "number"
    },
    "device": {
      "type": "string"
    },
    "status": {
      "type": "object",
      "properties": {
        "action_sent": {
          "type": "string"
        },
        "response_received": {
          "type": "string"
        }
      }
    },
    "result": {
      "type": "object",
      "properties": {
        "status": {
          "type": "number"
        }
      }
    },
    "result_code": {
      "type": "string"
    },
    "finished": {
      "type": "boolean"
    },
    "changed_at": {
      "type": "string"
    },
    "created_at": {
      "type": "string"
    }
  }
}

User Management ¶

File Transfer ¶