Get Started

The DeviceHive API is the central part of the framework which allows different components to interact with each other. The API provides access to information about registered components in the system, and allows them to exchange messages in real time.

Use Cases

There are three types of consumers of the DeviceHive API, as shown on the diagram below:

Use Cases

Device

Device is a unit that runs microcode, and it communicates with the API in the following cases:

  • When started, device registers within the framework by passing unique identifier, display name and other meta-information.
  • Device sends notifications with an arbitrary content format to notify other components about the changes in the device's environment.
  • Device listens for commands issued by other components and executes them in an appropriate way.

Client

Client is an application that is used to monitor and/or control devices. It could be a user interface, or completely automated software that manages the entire device network. Clients may invoke the API in the following use cases:

  • Client enumerates all the devices in the network, view their status and other meta-information.
  • Client listens for device notifications and processes them in an appropriate way.
  • Client sends commands to devices to trigger any logic on the device side.

Administrator

Administrator controls all aspects of the environment with the full access to the API. Commonly, administrators will need to use this API in the following cases:

  • Administrator creates and manages API users and access keys (clients and other administrators).
  • Administrator creates and manages device networks and associates users with them.
  • Administrator monitors devices and all dispatched notifications and commands.

Resources

The DeviceHive API is a RESTful service, which operates on several resource types. The diagram below reflects all used resource types and their relationships:

Data Model
  • User: represents a user with credentials and API access rights (client or administrator).
  • Network: represents an isolation entity that encapsulates multiple devices with controlled access.
  • Device: represents a unit that runs microcode.
  • Device Class: represents an entity that holds all meta-information about particular type of devices.
  • Equipment: represents meta-information about one unit of equipment devices have onboard.
  • Device Notification: represents a message dispatched by devices for clients.
  • Device Command: represents a message dispatched by clients for devices.
  • Access Key: represents an access key with specific API access rights.

Server Processes

Besides the CRUD access to all resources listed above, the API includes several business features implemented on the server side. The sections below provide more information about their implementation.

Message routing

One of the primary features of the service is to connect devices with clients in real-time. This is achieved on the server-side by routing new commands and notification to their recipients with minimal delays.

There are three methods for API clients to receive incoming messages:

  1. Polling: The client periodically requests the server to retrieve new commands or notifications. The request must include the waitTimeout=0 parameter to disable waiting on the server.
  2. Long Polling: The client makes request to the server, but the server responds only when a new message is available, or if the waiting timeout is expired (specified in the waitTimeout parameter). That approach is generally more efficient and minimizes message receive delays.
  3. WebSocket: A separate WebSocket API allows clients to open persistent connections with the server, subscribe to particular commands or notifications and then receive messages from the server. The URL of the WebSocket endpoint could be retrieved using the ApiInfo: get call.

In all three methods it's possible to specify the timestamp parameter as starting date/time (non-inclusive) for incoming messages. If that parameter is omitted, the server's current timestamp is taken instead.

In order to receive all messages in the right order, the clients should always pass the timestamp of the last received message when polling or subscribing. If no messages were ever received, the client should get the server's current timestamp using the ApiInfo: get call and use it until a new message is received.

Tracking device equipment state

One of the useful features provided by the server is tracking the most recent state of device equipment (e.g. sensors, meters, etc.). The API clients may use the Device: equipment operation to receive the current state of the device equipment.

In order to support that functionality, devices must send properly formatted notifications about changes in the current equipment state. The notification resource must include the following properties:

  • notification: Must be 'equipment'.
  • parameters: Must be a JSON object with the 'equipment' property containing the corresponding equipment code. Other properties in the JSON object should reflect the equipment state.

Server-originated notifications

Devices are not the only source of notifications in the system: the server also generates special notifications about various device events. The list below includes all such notifications with their description:

  • $device-add: Dispatched once for newly registered device. The notification includes all device properties specified during registration.
  • $device-update: Dispatched every time device properties are updated (e.g. device name, status, etc.). The notification includes only the changed properties. If no properties were changed, the notification parameters property is an empty object.

Automatic Offline device status

The server provides a capability to auto-update the device status to Offline after certain period of inactivity. A device is considered to be inactive when it is not persistently connected and it does not send any notifications for a specified period of time. Please note the status is not currently reverted to the original value when a device is brought back online.

The feature is enabled, if a corresponding device class includes a positive offlineTimeout property.

Server Extensibility

The DeviceHive allows to extend server logic by implementing the IMessageManager interface in a separate plug-in assembly and referencing it from the configuration file. The plug-ins can inspect all transmitted messages and apply custom logic as necessary.

Authentication

The API supports three types of authentication: User, Access Key and Device.

User

The users are authenticated using HTTP Basic Authentication.

The access is provided based on authenticated user role (Client or Administrator), please refer to the Reference for the list of available resources and methods for each user role.

Access Key

Access key authentication is useful, when third-party applications, clients or devices have to access the DeviceHive API. It is possible limit the rights of a particular access key to specific resources and actions, networks, devices, as well as restrict usage of the key to a range of source domains and/or IP subnets.

The access key is passed in the Authorization HTTP header using the Bearer scheme as follows:

  • Authorization: Bearer <access_key>

Device

Another way how devices could authenticate themselves is by passing two custom HTTP headers:

  • Auth-DeviceID: Device unique identifier.
  • Auth-DeviceKey: Device authentication key.

Both device unique identifier and authentication key are specified during device registration.

Response Codes

The API uses HTTP Status Codes to notify clients about the status of requested operation. As usual, the 2xx codes indicate the operation has been completed successfully, the 4xx codes indicate client errors, and 5xx codes reflect server errors.

The list below provides some additional information about common status codes returned by API operations:

  • 200 OK: Requested operation completed successfully. The response body includes a resource object as specified in the API reference.
  • 201 Created: Requested operation completed successfully and a new resource has been created (typically for POST operations). The HTTP Location header includes the URL of created resource. The response body includes created resource object as specified in the API reference.
  • 204 No Content: Requested operation completed successfully and there is no resource in the response body (typically for DELETE operations).
  • 400 Bad Request: The client did not specify all required parameters or some parameters passed are invalid. The response body includes a JSON object with the 'message' property describing the error details.
  • 401 Unauthorized: The client did not specify authentication headers or access to the requested resource is not allowed for the current identity. The response body includes a JSON object with the 'message' property describing the error details.
  • 403 Forbidden: The server could not complete the requested operation with the specified parameters (e.g. network with such name already exists). The response body includes a JSON object with the 'message' property describing the error details.
  • 404 Not Found: The specified resource is not found. The response body includes a JSON object with the 'message' property describing the error details.
  • 405 Method Not Allowed: The specified operation for the current resource is not allowed. The response body includes a JSON object with the 'message' property describing the error details.
  • 500 Internal Server Error: The server error occurred while processing requested operation. The expected response format is not documented.

REST API Reference

The DeviceHive REST API exposes the following resources:

AccessKey

Represents an access key to this API.

For AccessKey resource details, see the resource representation page.

Method Authorization Uri Description
list User or Key (ManageAccessKey) GET /user/{userId}/accesskey Gets list of access keys and their permissions.
get User or Key (ManageAccessKey) GET /user/{userId}/accesskey/{id} Gets information about access key and its permissions.
insert User or Key (ManageAccessKey) POST /user/{userId}/accesskey Creates new access key.
update User or Key (ManageAccessKey) PUT /user/{userId}/accesskey/{id} Updates an existing access key.
delete User or Key (ManageAccessKey) DELETE /user/{userId}/accesskey/{id} Deletes an existing access key.

ApiInfo

Represents meta-information about the current API.

For ApiInfo resource details, see the resource representation page.

Method Authorization Uri Description
get None GET /info Gets meta-information of the current API.

Authentication

Represents utility methods for user authentication and generating session-level access tokens.

For Authentication resource details, see the resource representation page.

Method Authorization Uri Description
config None GET /info/config/auth Gets information about supported authentication providers.
login None POST /auth/accesskey Authenticates a user and returns a session-level access key.
logout User or Key (GetCurrentUser) DELETE /auth/accesskey Invalidates the session-level token.

Device

Represents a device, a unit that runs microcode and communicates to this API.

For Device resource details, see the resource representation page.

Method Authorization Uri Description
list User or Key (GetDevice) GET /device Gets list of devices.
get User or Device or Key (GetDevice) GET /device/{id} Gets information about device.
register User or Device or Key (RegisterDevice) PUT /device/{id} Registers or updates a device. For initial device registration, only 'name' and 'deviceClass' properties are required.
delete User or Device or Key (RegisterDevice) DELETE /device/{id} Deletes an existing device.
equipment User or Key (GetDeviceState) GET /device/{id}/equipment

Gets current state of device equipment.

The equipment state is tracked by framework and it could be updated by sending 'equipment' notification with the following parameters:

  • equipment: equipment code
  • parameters: current equipment state

DeviceClass

Represents a device class which holds meta-information about devices.

For DeviceClass resource details, see the resource representation page.

Method Authorization Uri Description
list Administrator or Key (ManageDeviceClass) GET /device/class Gets list of device classes.
get User or Key (GetDevice) GET /device/class/{id} Gets information about device class and its equipment.
insert Administrator or Key (ManageDeviceClass) POST /device/class Creates new device class.
update Administrator or Key (ManageDeviceClass) PUT /device/class/{id} Updates an existing device class.
delete Administrator or Key (ManageDeviceClass) DELETE /device/class/{id} Deletes an existing device class.

DeviceCommand

Represents a device command, a unit of information sent to devices.

For DeviceCommand resource details, see the resource representation page.

Method Authorization Uri Description
query User or Device or Key (GetDeviceCommand) GET /device/{deviceGuid}/command Queries device commands.
get User or Device or Key (GetDeviceCommand) GET /device/{deviceGuid}/command/{id} Gets information about device command.
insert User or Key (CreateDeviceCommand) POST /device/{deviceGuid}/command Creates new device command.
update User or Device or Key (UpdateDeviceCommand) PUT /device/{deviceGuid}/command/{id} Updates an existing device command.
poll User or Device or Key (GetDeviceCommand) GET /device/{deviceGuid}/command/poll

Polls new device commands.

This method returns all device commands that were created after specified timestamp.

In the case when no commands were found, the method blocks until new command is received. If no commands are received within the waitTimeout period, the server returns an empty response. In this case, to continue polling, the client should repeat the call with the same timestamp value.

wait User or Key (GetDeviceCommand) GET /device/{deviceGuid}/command/{id}/poll

Waits for a command to be processed.

This method returns a command only if it has been processed by a device.

In the case when command is not processed, the method blocks until device acknowledges command execution. If the command is not processed within the waitTimeout period, the server returns an empty response. In this case, to continue polling, the client should repeat the call.

pollMany User or Key (GetDeviceCommand) GET /device/command/poll

Polls new device commands.

This method returns all device commands that were created after specified timestamp.

In the case when no commands were found, the method blocks until new command is received. If no commands are received within the waitTimeout period, the server returns an empty response. In this case, to continue polling, the client should repeat the call with the same timestamp value.

DeviceNotification

Represents a device notification, a unit of information dispatched from devices.

For DeviceNotification resource details, see the resource representation page.

Method Authorization Uri Description
query User or Key (GetDeviceNotification) GET /device/{deviceGuid}/notification Queries device notifications.
get User or Key (GetDeviceNotification) GET /device/{deviceGuid}/notification/{id} Gets information about device notification.
insert User or Device or Key (CreateDeviceNotification) POST /device/{deviceGuid}/notification Creates new device notification.
poll User or Key (GetDeviceNotification) GET /device/{deviceGuid}/notification/poll

Polls new device notifications.

This method returns all device notifications that were created after specified timestamp.

In the case when no notifications were found, the method blocks until new notification is received. If no notifications are received within the waitTimeout period, the server returns an empty response. In this case, to continue polling, the client should repeat the call with the same timestamp value.

pollMany User or Key (GetDeviceNotification) GET /device/notification/poll

Polls new device notifications.

This method returns all device notifications that were created after specified timestamp.

In the case when no notifications were found, the method blocks until new notification is received. If no notifications are received within the waitTimeout period, the server returns an empty response. In this case, to continue polling, the client should repeat the call with the same timestamp value.

Network

Represents a network, an isolated area where devices reside.

For Network resource details, see the resource representation page.

Method Authorization Uri Description
list User or Key (GetNetwork) GET /network Gets list of device networks.

The result list is limited to networks the client has access to.

get User or Key (GetNetwork) GET /network/{id} Gets information about device network and its devices.
insert Administrator or Key (ManageNetwork) POST /network Creates new device network.
update Administrator or Key (ManageNetwork) PUT /network/{id} Updates an existing device network.
delete Administrator or Key (ManageNetwork) DELETE /network/{id} Deletes an existing device network.

OAuthClient

Represents a client with the access to the DeviceHive OAuth API.

For OAuthClient resource details, see the resource representation page.

Method Authorization Uri Description
list None GET /oauth/client Gets list of OAuth clients.
get None GET /oauth/client/{id} Gets information about OAuth client.
insert Administrator or Key (ManageOAuthClient) POST /oauth/client Creates new OAuth client.
update Administrator or Key (ManageOAuthClient) PUT /oauth/client/{id} Updates an existing OAuth client.
delete Administrator or Key (ManageOAuthClient) DELETE /oauth/client/{id} Deletes an existing OAuth client.

OAuthGrant

Represents an OAuth permission grant.

For OAuthGrant resource details, see the resource representation page.

Method Authorization Uri Description
list User or Key (ManageOAuthGrant) GET /user/{userId}/oauth/grant Gets list of OAuth grants.
get User or Key (ManageOAuthGrant) GET /user/{userId}/oauth/grant/{id} Gets information about OAuth grant.
insert User or Key (ManageOAuthGrant) POST /user/{userId}/oauth/grant Creates new OAuth grant.
update User or Key (ManageOAuthGrant) PUT /user/{userId}/oauth/grant/{id} Updates an existing OAuth grant.
delete User or Key (ManageOAuthGrant) DELETE /user/{userId}/oauth/grant/{id} Deletes an existing OAuth grant.

User

Represents a user to this API.

For User resource details, see the resource representation page.

Method Authorization Uri Description
list Administrator or Key (ManageUser) GET /user Gets list of users.
get User or Key (GetCurrentUser) GET /user/{id} Gets information about user and its assigned networks.

Only administrators are allowed to get information about any user. User-level accounts can only retrieve information about themselves.

insert Administrator or Key (ManageUser) POST /user Creates new user.
update User or Key (UpdateCurrentUser) PUT /user/{id} Updates an existing user.

Only administrators are allowed to update any property of any user. User-level accounts can only change their own password in case:

  • They already have a password.
  • They provide a valid current password in the 'oldPassword' property.
delete Administrator or Key (ManageUser) DELETE /user/{id} Deletes an existing user.
getNetwork Administrator or Key (ManageUser) GET /user/{id}/network/{networkId} Gets information about user/network association.
assignNetwork Administrator or Key (ManageUser) PUT /user/{id}/network/{networkId} Associates network with the user.
unassignNetwork Administrator or Key (ManageUser) DELETE /user/{id}/network/{networkId} Removes association between network and user.

WebSocket API Reference

The DeviceHive WebSocket API exposes the following services:

Client

The service allows clients to exchange messages with the DeviceHive server using a single persistent connection.

After connection is eshtablished, clients need to authenticate using their login and password or access key, and then start sending commands to devices using the command/insert message. As soon as a command is processed by a device, the server sends the command/update message.

Clients may also subscribe to device notifications using the notification/subscribe message and then start receiving server-originated messages about new device notifications.

For the Client service details, see the service information page.

Message Originator Authorization Description
authenticate Client None Authenticates a client. Either login and password or accessKey parameters must be passed.
command/insert Client User or Key (CreateDeviceCommand) Creates new device command.
command/subscribe Client User or Key (GetDeviceCommand) Subscribes to device commands. After subscription is completed, the server will start to send command/insert messages to the connected user.
command/unsubscribe Client User or Key (GetDeviceCommand) Unsubscribes from device commands.
command/update Client User or Key (UpdateDeviceCommand) Updates an existing device command on behalf of device.
notification/insert Client User or Key (CreateDeviceNotification) Creates new device notification on behalf of device.
notification/subscribe Client User or Key (GetDeviceNotification) Subscribes to device notifications. After subscription is completed, the server will start to send notification/insert messages to the connected user.
notification/unsubscribe Client User or Key (GetDeviceNotification) Unsubscribes from device notifications.
server/info Client None Gets meta-information about the current API.
srv: command/insert Server n/a Notifies the user about new device command.
srv: command/update Server n/a Notifies the user about a command has been processed by a device. These messages are sent only for commands created by the current user within the current connection.
srv: notification/insert Server n/a Notifies the user about new device notification.

Device

The service allows devices to exchange messages with the DeviceHive server using a single persistent connection.

After connection is eshtablished, devices need to register using the device/save message, perform authentication and then start sending notifications using the notification/insert message.

Devices may also subscribe to commands using the command/subscrive message and then start receiving server-originated messages about new commands.

It is also possible not to authenticate as concrete device, but rather send device identifier and key in each request. That scenario is common for gateways which typically proxy multiple devices and use a single connection to the server.

For the Device service details, see the service information page.

Message Originator Authorization Description
authenticate Device None Authenticates a device. After successful authentication, all subsequent messages may exclude deviceId and deviceKey parameters.
command/subscribe Device Device Subscribes the device to commands. After subscription is completed, the server will start to send command/insert messages to the connected device.
command/unsubscribe Device Device Unsubscribes the device from commands.
command/update Device Device Updates an existing device command.
device/get Device Device Gets information about the current device.
device/save Device Device Registers or updates a device.
notification/insert Device Device Creates new device notification.
server/info Device None Gets meta-information of the current API.
srv: command/insert Server n/a Notifies the device about new command.

AccessKey

Represents an access key to this API.

Methods

Method Authorization Uri Description
list User or Key (ManageAccessKey) GET /user/{userId}/accesskey Gets list of access keys and their permissions.
get User or Key (ManageAccessKey) GET /user/{userId}/accesskey/{id} Gets information about access key and its permissions.
insert User or Key (ManageAccessKey) POST /user/{userId}/accesskey Creates new access key.
update User or Key (ManageAccessKey) PUT /user/{userId}/accesskey/{id} Updates an existing access key.
delete User or Key (ManageAccessKey) DELETE /user/{userId}/accesskey/{id} Deletes an existing access key.

Resource Representation

{
    "id": {integer},
    "type": {integer},
    "label": {string},
    "key": {string},
    "expirationDate": {datetime},
    "permissions": [
        {
            "domains": {array},
            "subnets": {array},
            "actions": {array},
            "networkIds": {array},
            "deviceGuids": {array}
        }
    ]
}
Property Name Type Description
id integer Access key identifier.
type integer Access key type. Available values:
  • 0: Default
  • 1: Session (with sliding expiration)
  • 2: OAuth (issued via OAuth2 token endpoint)
label string Access key label.
key string Access key value.
expirationDate datetime Expiration date (UTC).
permissions array A collection of associated permission objects.
permissions[].domains array A collection of domains to which this permission applies. Only API requests from the specified domains will be authorized with this permission. Set to null to allow callees from any domain to make specified actions.
permissions[].subnets array A collection of source IP addresses or subnets to which this permission applies. Only API requests from the specified addresses/subnets will be authorized with this permission. Set to null to allow any callees to make specified actions. Subnet format example: 12.12.12.12, or 12.12.12.0/24
permissions[].actions array A collection of allowed actions. Available values:
  • GetNetwork: get information about network
  • GetDevice: get information about device and device class
  • GetDeviceState: get information about current device equipment state
  • GetDeviceNotification: get or subscribe to device notifications
  • GetDeviceCommand: get or subscribe to commands sent to device
  • RegisterDevice: register a device
  • CreateDeviceNotification: post notifications on behalf of device
  • CreateDeviceCommand: post commands to device
  • UpdateDeviceCommand: update status of commands on behalf of device
permissions[].networkIds array A collection of identifiers of allowed networks. Only API requests for devices within the allowed networks will be authorized with this permission. Set to null to allow callees to access all networks permitted for the owner user.
permissions[].deviceGuids array A collection of unique identifiers of allowed devices. Only API requests for allowed devices will be authorized with this permission. Set to null to allow callees to access all devices permitted for the owner user.

AccessKey: list

Gets list of access keys and their permissions.

Request

HTTP Request

GET /user/{userId}/accesskey

Parameters

Parameter Name Required Type Description
userId Yes integer User identifier. Use the 'current' keyword to list access keys of the current user.
label No string Filter by access key label.
labelPattern No string Filter by access key label pattern.
type No integer Filter by acess key type.
sortField No string Result list sort field. Available values are ID and Label.
sortOrder No string Result list sort order. Available values are ASC and DESC.
take No integer Number of records to take from the result list.
skip No integer Number of records to skip from the result list.

Authorization

User or Key (ManageAccessKey)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns array of AccessKey resources in the response body.

Property Name Type Description
id integer Access key identifier.
type integer Access key type. Available values:
  • 0: Default
  • 1: Session (with sliding expiration)
  • 2: OAuth (issued via OAuth2 token endpoint)
label string Access key label.
key string Access key value.
expirationDate datetime Expiration date (UTC).
permissions array A collection of associated permission objects.
permissions[].domains array A collection of domains to which this permission applies. Only API requests from the specified domains will be authorized with this permission. Set to null to allow callees from any domain to make specified actions.
permissions[].subnets array A collection of source IP addresses or subnets to which this permission applies. Only API requests from the specified addresses/subnets will be authorized with this permission. Set to null to allow any callees to make specified actions. Subnet format example: 12.12.12.12, or 12.12.12.0/24
permissions[].actions array A collection of allowed actions. Available values:
  • GetNetwork: get information about network
  • GetDevice: get information about device and device class
  • GetDeviceState: get information about current device equipment state
  • GetDeviceNotification: get or subscribe to device notifications
  • GetDeviceCommand: get or subscribe to commands sent to device
  • RegisterDevice: register a device
  • CreateDeviceNotification: post notifications on behalf of device
  • CreateDeviceCommand: post commands to device
  • UpdateDeviceCommand: update status of commands on behalf of device
permissions[].networkIds array A collection of identifiers of allowed networks. Only API requests for devices within the allowed networks will be authorized with this permission. Set to null to allow callees to access all networks permitted for the owner user.
permissions[].deviceGuids array A collection of unique identifiers of allowed devices. Only API requests for allowed devices will be authorized with this permission. Set to null to allow callees to access all devices permitted for the owner user.

AccessKey: get

Gets information about access key and its permissions.

Request

HTTP Request

GET /user/{userId}/accesskey/{id}

Parameters

Parameter Name Required Type Description
userId Yes integer User identifier. Use the 'current' keyword to get access key of the current user.
id Yes integer Access key identifier.

Authorization

User or Key (ManageAccessKey)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns a AccessKey resource in the response body.

Property Name Type Description
id integer Access key identifier.
type integer Access key type. Available values:
  • 0: Default
  • 1: Session (with sliding expiration)
  • 2: OAuth (issued via OAuth2 token endpoint)
label string Access key label.
key string Access key value.
expirationDate datetime Expiration date (UTC).
permissions array A collection of associated permission objects.
permissions[].domains array A collection of domains to which this permission applies. Only API requests from the specified domains will be authorized with this permission. Set to null to allow callees from any domain to make specified actions.
permissions[].subnets array A collection of source IP addresses or subnets to which this permission applies. Only API requests from the specified addresses/subnets will be authorized with this permission. Set to null to allow any callees to make specified actions. Subnet format example: 12.12.12.12, or 12.12.12.0/24
permissions[].actions array A collection of allowed actions. Available values:
  • GetNetwork: get information about network
  • GetDevice: get information about device and device class
  • GetDeviceState: get information about current device equipment state
  • GetDeviceNotification: get or subscribe to device notifications
  • GetDeviceCommand: get or subscribe to commands sent to device
  • RegisterDevice: register a device
  • CreateDeviceNotification: post notifications on behalf of device
  • CreateDeviceCommand: post commands to device
  • UpdateDeviceCommand: update status of commands on behalf of device
permissions[].networkIds array A collection of identifiers of allowed networks. Only API requests for devices within the allowed networks will be authorized with this permission. Set to null to allow callees to access all networks permitted for the owner user.
permissions[].deviceGuids array A collection of unique identifiers of allowed devices. Only API requests for allowed devices will be authorized with this permission. Set to null to allow callees to access all devices permitted for the owner user.

AccessKey: insert

Creates new access key.

Request

HTTP Request

POST /user/{userId}/accesskey

Parameters

Parameter Name Required Type Description
userId Yes integer User identifier. Use the 'current' keyword to create access key for the current user.

Authorization

User or Key (ManageAccessKey)

Request Body

In the request body, supply a AccessKey resource.

Property Name Required Type Description
type No integer Access key type. Available values:
  • 0: Default
  • 1: Session (with sliding expiration)
  • 2: OAuth (issued via OAuth2 token endpoint)
label Yes string Access key label.
expirationDate No datetime Expiration date (UTC).
permissions No array A collection of associated permission objects.
permissions[].domains No array A collection of domains to which this permission applies. Only API requests from the specified domains will be authorized with this permission. Set to null to allow callees from any domain to make specified actions.
permissions[].subnets No array A collection of source IP addresses or subnets to which this permission applies. Only API requests from the specified addresses/subnets will be authorized with this permission. Set to null to allow any callees to make specified actions. Subnet format example: 12.12.12.12, or 12.12.12.0/24
permissions[].actions No array A collection of allowed actions. Available values:
  • GetNetwork: get information about network
  • GetDevice: get information about device and device class
  • GetDeviceState: get information about current device equipment state
  • GetDeviceNotification: get or subscribe to device notifications
  • GetDeviceCommand: get or subscribe to commands sent to device
  • RegisterDevice: register a device
  • CreateDeviceNotification: post notifications on behalf of device
  • CreateDeviceCommand: post commands to device
  • UpdateDeviceCommand: update status of commands on behalf of device
permissions[].networkIds No array A collection of identifiers of allowed networks. Only API requests for devices within the allowed networks will be authorized with this permission. Set to null to allow callees to access all networks permitted for the owner user.
permissions[].deviceGuids No array A collection of unique identifiers of allowed devices. Only API requests for allowed devices will be authorized with this permission. Set to null to allow callees to access all devices permitted for the owner user.

Response

If successful, this method returns a AccessKey resource in the response body.

Property Name Type Description
id integer Access key identifier.
key string Access key value.

AccessKey: update

Updates an existing access key.

Request

HTTP Request

PUT /user/{userId}/accesskey/{id}

Parameters

Parameter Name Required Type Description
userId Yes integer User identifier. Use the 'current' keyword to update access key of the current user.
id Yes integer Access key identifier.

Authorization

User or Key (ManageAccessKey)

Request Body

In the request body, supply a AccessKey resource.

Property Name Required Type Description
type No integer Access key type. Available values:
  • 0: Default
  • 1: Session (with sliding expiration)
  • 2: OAuth (issued via OAuth2 token endpoint)
label No string Access key label.
expirationDate No datetime Expiration date (UTC).
permissions No array A collection of associated permission objects.
permissions[].domains No array A collection of domains to which this permission applies. Only API requests from the specified domains will be authorized with this permission. Set to null to allow callees from any domain to make specified actions.
permissions[].subnets No array A collection of source IP addresses or subnets to which this permission applies. Only API requests from the specified addresses/subnets will be authorized with this permission. Set to null to allow any callees to make specified actions. Subnet format example: 12.12.12.12, or 12.12.12.0/24
permissions[].actions No array A collection of allowed actions. Available values:
  • GetNetwork: get information about network
  • GetDevice: get information about device and device class
  • GetDeviceState: get information about current device equipment state
  • GetDeviceNotification: get or subscribe to device notifications
  • GetDeviceCommand: get or subscribe to commands sent to device
  • RegisterDevice: register a device
  • CreateDeviceNotification: post notifications on behalf of device
  • CreateDeviceCommand: post commands to device
  • UpdateDeviceCommand: update status of commands on behalf of device
permissions[].networkIds No array A collection of identifiers of allowed networks. Only API requests for devices within the allowed networks will be authorized with this permission. Set to null to allow callees to access all networks permitted for the owner user.
permissions[].deviceGuids No array A collection of unique identifiers of allowed devices. Only API requests for allowed devices will be authorized with this permission. Set to null to allow callees to access all devices permitted for the owner user.

Response

If successful, this method returns an empty response body.

AccessKey: delete

Deletes an existing access key.

Request

HTTP Request

DELETE /user/{userId}/accesskey/{id}

Parameters

Parameter Name Required Type Description
userId Yes integer User identifier. Use the 'current' keyword to delete access key of the current user.
id Yes integer Access key identifier.

Authorization

User or Key (ManageAccessKey)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns an empty response body.

ApiInfo

Represents meta-information about the current API.

Methods

Method Authorization Uri Description
get None GET /info Gets meta-information of the current API.

Resource Representation

{
    "apiVersion": {string},
    "serverTimestamp": {datetime},
    "webSocketServerUrl": {string}
}
Property Name Type Description
apiVersion string API version.
serverTimestamp datetime Current server timestamp.
webSocketServerUrl string WebSocket server URL.

ApiInfo: get

Gets meta-information of the current API.

Request

HTTP Request

GET /info

Authorization

None

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns a ApiInfo resource in the response body.

Property Name Type Description
apiVersion string API version.
serverTimestamp datetime Current server timestamp.
webSocketServerUrl string WebSocket server URL.

Authentication

Represents utility methods for user authentication and generating session-level access tokens.

Methods

Method Authorization Uri Description
config None GET /info/config/auth Gets information about supported authentication providers.
login None POST /auth/accesskey Authenticates a user and returns a session-level access key.
logout User or Key (GetCurrentUser) DELETE /auth/accesskey Invalidates the session-level token.

Authentication: config

Gets information about supported authentication providers.

Request

HTTP Request

GET /info/config/auth

Authorization

None

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns the following resource in the response body.

Property Name Type Description
providers array List of authentication providers supported by this instance.
providers[].name string Provider name.
providers[].clientId string Client identifier of DeviceHive application within the third-party provider.
sessionTimeout integer User session timeout in seconds.

Authentication: login

Authenticates a user and returns a session-level access key.

Request

HTTP Request

POST /auth/accesskey

Authorization

None

Request Body

Do not supply a request body with this method.

Property Name Required Type Description
providerName Yes string Name of authentication provider to use. Please call the 'config' method to get the list of available authentication providers. Use the 'password' value for the password-based authentication.
login No string When using password authentication, specifies user login.
password No string When using password authentication, specifies user password.
code No string When using OAuth authentication, specifies authorization code received from provider.
redirect_uri No string When using OAuth authentication, specifies redirect uri used during authentication.
access_token No string When using OAuth implicit authentication, specifies access code issued to the DeviceHive application.

Response

If successful, this method returns the object with the following properties in the response body.

Property Name Type Description
key string Session-level access key to use with this API.
id int Session-level access key identifier.

Authentication: logout

Invalidates the session-level token.

Request

HTTP Request

DELETE /auth/accesskey

Authorization

User or Key (GetCurrentUser)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns an empty response body.

Device

Represents a device, a unit that runs microcode and communicates to this API.

Methods

Method Authorization Uri Description
list User or Key (GetDevice) GET /device Gets list of devices.
get User or Device or Key (GetDevice) GET /device/{id} Gets information about device.
register User or Device or Key (RegisterDevice) PUT /device/{id} Registers or updates a device. For initial device registration, only 'name' and 'deviceClass' properties are required.
delete User or Device or Key (RegisterDevice) DELETE /device/{id} Deletes an existing device.
equipment User or Key (GetDeviceState) GET /device/{id}/equipment

Gets current state of device equipment.

The equipment state is tracked by framework and it could be updated by sending 'equipment' notification with the following parameters:

  • equipment: equipment code
  • parameters: current equipment state

Resource Representation

{
    "id": {string},
    "key": {string},
    "name": {string},
    "status": {string},
    "data": {object},
    "network": {
        "id": {integer},
        "key": {string},
        "name": {string},
        "description": {string}
    },
    "deviceClass": {
        "id": {integer},
        "name": {string},
        "version": {string},
        "isPermanent": {boolean},
        "offlineTimeout": {integer},
        "data": {object},
        "equipment": [
            {
                "id": {integer},
                "name": {string},
                "code": {string},
                "type": {string},
                "data": {object}
            }
        ]
    }
}
Property Name Type Description
id string Device unique identifier.
key string Device authentication key. The key is set during device registration and it has to be provided for all subsequent calls initiated by device. The key maximum length is 64 characters.
name string Device display name.
status string Device operation status. The status is optional and it can be set to an arbitrary value, if applicable.

If device status monitoring feature is enabled, the framework will set status value to 'Offline' after defined period of inactivity.

data object Device data, a JSON object with an arbitrary structure.
network object Associated network object.
network.id integer Network identifier.
network.key string Optional key that is used to protect the network from unauthorized device registrations. When defined, devices will need to pass the key in order to register to the current network.
network.name string Network display name.
network.description string Network description.
deviceClass object Associated device class object.
deviceClass.id integer Device class identifier.
deviceClass.name string Device class display name.
deviceClass.version string Device class version.
deviceClass.isPermanent boolean Indicates whether device class is permanent. Permanent device classes could not be modified by devices during registration.
deviceClass.offlineTimeout integer If set, specifies inactivity timeout in seconds before the framework changes device status to 'Offline'. Device considered inactive when it's not persistently connected and does not send any notifications.
deviceClass.data object Device class data, a JSON object with an arbitrary structure.
deviceClass.equipment array A collection of associated equipment objects.
deviceClass.equipment[].id integer Equipment identifier.
deviceClass.equipment[].name string Equipment display name.
deviceClass.equipment[].code string Equipment code. It's used to reference particular equipment and it should be unique within a device class.
deviceClass.equipment[].type string Equipment type. An arbitrary string representing equipment capabilities.
deviceClass.equipment[].data object Equipment data, a JSON object with an arbitrary structure.

Device: list

Gets list of devices.

Request

HTTP Request

GET /device

Parameters

Parameter Name Required Type Description
name No string Filter by device name.
namePattern No string Filter by device name pattern.
status No string Filter by device status.
networkId No integer Filter by associated network identifier.
networkName No string Filter by associated network name.
deviceClassId No integer Filter by associated device class identifier.
deviceClassName No string Filter by associated device class name.
deviceClassVersion No string Filter by associated device class version.
sortField No string Result list sort field. Available values are Name, Status, Network and DeviceClass.
sortOrder No string Result list sort order. Available values are ASC and DESC.
take No integer Number of records to take from the result list.
skip No integer Number of records to skip from the result list.

Authorization

User or Key (GetDevice)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns array of Device resources in the response body.

Property Name Type Description
id string Device unique identifier.
name string Device display name.
status string Device operation status. The status is optional and it can be set to an arbitrary value, if applicable.

If device status monitoring feature is enabled, the framework will set status value to 'Offline' after defined period of inactivity.

data object Device data, a JSON object with an arbitrary structure.
network object Associated network object.
network.id integer Network identifier.
network.key string Optional key that is used to protect the network from unauthorized device registrations. When defined, devices will need to pass the key in order to register to the current network.
network.name string Network display name.
network.description string Network description.
deviceClass object Associated device class object.
deviceClass.id integer Device class identifier.
deviceClass.name string Device class display name.
deviceClass.version string Device class version.
deviceClass.isPermanent boolean Indicates whether device class is permanent. Permanent device classes could not be modified by devices during registration.
deviceClass.offlineTimeout integer If set, specifies inactivity timeout in seconds before the framework changes device status to 'Offline'. Device considered inactive when it's not persistently connected and does not send any notifications.
deviceClass.data object Device class data, a JSON object with an arbitrary structure.
deviceClass.equipment array A collection of associated equipment objects.
deviceClass.equipment[].id integer Equipment identifier.
deviceClass.equipment[].name string Equipment display name.
deviceClass.equipment[].code string Equipment code. It's used to reference particular equipment and it should be unique within a device class.
deviceClass.equipment[].type string Equipment type. An arbitrary string representing equipment capabilities.
deviceClass.equipment[].data object Equipment data, a JSON object with an arbitrary structure.

Device: get

Gets information about device.

Request

HTTP Request

GET /device/{id}

Parameters

Parameter Name Required Type Description
id Yes string Device unique identifier.

Authorization

User or Device or Key (GetDevice)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns a Device resource in the response body.

Property Name Type Description
id string Device unique identifier.
name string Device display name.
status string Device operation status. The status is optional and it can be set to an arbitrary value, if applicable.

If device status monitoring feature is enabled, the framework will set status value to 'Offline' after defined period of inactivity.

data object Device data, a JSON object with an arbitrary structure.
network object Associated network object.
network.id integer Network identifier.
network.key string Optional key that is used to protect the network from unauthorized device registrations. When defined, devices will need to pass the key in order to register to the current network.
network.name string Network display name.
network.description string Network description.
deviceClass object Associated device class object.
deviceClass.id integer Device class identifier.
deviceClass.name string Device class display name.
deviceClass.version string Device class version.
deviceClass.isPermanent boolean Indicates whether device class is permanent. Permanent device classes could not be modified by devices during registration.
deviceClass.offlineTimeout integer If set, specifies inactivity timeout in seconds before the framework changes device status to 'Offline'. Device considered inactive when it's not persistently connected and does not send any notifications.
deviceClass.data object Device class data, a JSON object with an arbitrary structure.
deviceClass.equipment array A collection of associated equipment objects.
deviceClass.equipment[].id integer Equipment identifier.
deviceClass.equipment[].name string Equipment display name.
deviceClass.equipment[].code string Equipment code. It's used to reference particular equipment and it should be unique within a device class.
deviceClass.equipment[].type string Equipment type. An arbitrary string representing equipment capabilities.
deviceClass.equipment[].data object Equipment data, a JSON object with an arbitrary structure.

Device: register

Registers or updates a device. For initial device registration, only 'name' and 'deviceClass' properties are required.

Request

HTTP Request

PUT /device/{id}

Parameters

Parameter Name Required Type Description
id Yes string Device unique identifier.

Authorization

User or Device or Key (RegisterDevice)

Request Body

In the request body, supply a Device resource.

Property Name Required Type Description
key No string Device authentication key. The key is set during device registration and it has to be provided for all subsequent calls initiated by device. The key maximum length is 64 characters.
name No string Device display name.
status No string Device operation status. The status is optional and it can be set to an arbitrary value, if applicable.

If device status monitoring feature is enabled, the framework will set status value to 'Offline' after defined period of inactivity.

data No object Device data, a JSON object with an arbitrary structure.
network No object

A Network object which includes name property to match.

In case when the target network is protected with a key, the key value must also be included.

For test deployments, any non-existing networks are automatically created.

network.key No string Optional key that is used to protect the network from unauthorized device registrations. When defined, devices will need to pass the key in order to register to the current network.
network.name Yes string Network display name.
network.description No string Network description.
deviceClass No object

A DeviceClass object which includes name and version properties to match.

The device class objects are automatically created/updated unless the DeviceClass.IsPermanent flag is set.

deviceClass.name Yes string Device class display name.
deviceClass.version Yes string Device class version.
deviceClass.isPermanent No boolean Indicates whether device class is permanent. Permanent device classes could not be modified by devices during registration.
deviceClass.offlineTimeout No integer If set, specifies inactivity timeout in seconds before the framework changes device status to 'Offline'. Device considered inactive when it's not persistently connected and does not send any notifications.
deviceClass.data No object Device class data, a JSON object with an arbitrary structure.
deviceClass.equipment No array A collection of associated equipment objects.
deviceClass.equipment[].name Yes string Equipment display name.
deviceClass.equipment[].code Yes string Equipment code. It's used to reference particular equipment and it should be unique within a device class.
deviceClass.equipment[].type Yes string Equipment type. An arbitrary string representing equipment capabilities.
deviceClass.equipment[].data No object Equipment data, a JSON object with an arbitrary structure.

Response

If successful, this method returns an empty response body.

Device: delete

Deletes an existing device.

Request

HTTP Request

DELETE /device/{id}

Parameters

Parameter Name Required Type Description
id Yes string Device unique identifier.

Authorization

User or Device or Key (RegisterDevice)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns an empty response body.

Device: equipment

Gets current state of device equipment.

The equipment state is tracked by framework and it could be updated by sending 'equipment' notification with the following parameters:

  • equipment: equipment code
  • parameters: current equipment state

Request

HTTP Request

GET /device/{id}/equipment

Parameters

Parameter Name Required Type Description
id Yes string Device unique identifier.

Authorization

User or Key (GetDeviceState)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns array of the following structures in the response body.

Property Name Type Description
id string Equipment code.
timestamp datetime Equipment state timestamp.
parameters object Current equipment state.

DeviceClass

Represents a device class which holds meta-information about devices.

Methods

Method Authorization Uri Description
list Administrator or Key (ManageDeviceClass) GET /device/class Gets list of device classes.
get User or Key (GetDevice) GET /device/class/{id} Gets information about device class and its equipment.
insert Administrator or Key (ManageDeviceClass) POST /device/class Creates new device class.
update Administrator or Key (ManageDeviceClass) PUT /device/class/{id} Updates an existing device class.
delete Administrator or Key (ManageDeviceClass) DELETE /device/class/{id} Deletes an existing device class.

Resource Representation

{
    "id": {integer},
    "name": {string},
    "version": {string},
    "isPermanent": {boolean},
    "offlineTimeout": {integer},
    "data": {object},
    "equipment": [
        {
            "id": {integer},
            "name": {string},
            "code": {string},
            "type": {string},
            "data": {object}
        }
    ]
}
Property Name Type Description
id integer Device class identifier.
name string Device class display name.
version string Device class version.
isPermanent boolean Indicates whether device class is permanent. Permanent device classes could not be modified by devices during registration.
offlineTimeout integer If set, specifies inactivity timeout in seconds before the framework changes device status to 'Offline'. Device considered inactive when it's not persistently connected and does not send any notifications.
data object Device class data, a JSON object with an arbitrary structure.
equipment array A collection of associated equipment objects.
equipment[].id integer Equipment identifier.
equipment[].name string Equipment display name.
equipment[].code string Equipment code. It's used to reference particular equipment and it should be unique within a device class.
equipment[].type string Equipment type. An arbitrary string representing equipment capabilities.
equipment[].data object Equipment data, a JSON object with an arbitrary structure.

DeviceClass: list

Gets list of device classes.

Request

HTTP Request

GET /device/class

Parameters

Parameter Name Required Type Description
name No string Filter by device class name.
namePattern No string Filter by device class name pattern.
version No string Filter by device class version.
sortField No string Result list sort field. Available values are ID and Name.
sortOrder No string Result list sort order. Available values are ASC and DESC.
take No integer Number of records to take from the result list.
skip No integer Number of records to skip from the result list.

Authorization

Administrator or Key (ManageDeviceClass)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns array of DeviceClass resources in the response body.

Property Name Type Description
id integer Device class identifier.
name string Device class display name.
version string Device class version.
isPermanent boolean Indicates whether device class is permanent. Permanent device classes could not be modified by devices during registration.
offlineTimeout integer If set, specifies inactivity timeout in seconds before the framework changes device status to 'Offline'. Device considered inactive when it's not persistently connected and does not send any notifications.
data object Device class data, a JSON object with an arbitrary structure.
equipment array A collection of associated equipment objects.
equipment[].id integer Equipment identifier.
equipment[].name string Equipment display name.
equipment[].code string Equipment code. It's used to reference particular equipment and it should be unique within a device class.
equipment[].type string Equipment type. An arbitrary string representing equipment capabilities.
equipment[].data object Equipment data, a JSON object with an arbitrary structure.

DeviceClass: get

Gets information about device class and its equipment.

Request

HTTP Request

GET /device/class/{id}

Parameters

Parameter Name Required Type Description
id Yes integer Device class identifier.

Authorization

User or Key (GetDevice)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns a DeviceClass resource in the response body.

Property Name Type Description
id integer Device class identifier.
name string Device class display name.
version string Device class version.
isPermanent boolean Indicates whether device class is permanent. Permanent device classes could not be modified by devices during registration.
offlineTimeout integer If set, specifies inactivity timeout in seconds before the framework changes device status to 'Offline'. Device considered inactive when it's not persistently connected and does not send any notifications.
data object Device class data, a JSON object with an arbitrary structure.
equipment array A collection of associated equipment objects.
equipment[].id integer Equipment identifier.
equipment[].name string Equipment display name.
equipment[].code string Equipment code. It's used to reference particular equipment and it should be unique within a device class.
equipment[].type string Equipment type. An arbitrary string representing equipment capabilities.
equipment[].data object Equipment data, a JSON object with an arbitrary structure.

DeviceClass: insert

Creates new device class.

Request

HTTP Request

POST /device/class

Authorization

Administrator or Key (ManageDeviceClass)

Request Body

In the request body, supply a DeviceClass resource.

Property Name Required Type Description
name Yes string Device class display name.
version Yes string Device class version.
isPermanent No boolean Indicates whether device class is permanent. Permanent device classes could not be modified by devices during registration.
offlineTimeout No integer If set, specifies inactivity timeout in seconds before the framework changes device status to 'Offline'. Device considered inactive when it's not persistently connected and does not send any notifications.
data No object Device class data, a JSON object with an arbitrary structure.
equipment No array A collection of associated equipment objects.
equipment[].name Yes string Equipment display name.
equipment[].code Yes string Equipment code. It's used to reference particular equipment and it should be unique within a device class.
equipment[].type Yes string Equipment type. An arbitrary string representing equipment capabilities.
equipment[].data No object Equipment data, a JSON object with an arbitrary structure.

Response

If successful, this method returns a DeviceClass resource in the response body.

Property Name Type Description
id integer Device class identifier.

DeviceClass: update

Updates an existing device class.

Request

HTTP Request

PUT /device/class/{id}

Parameters

Parameter Name Required Type Description
id Yes integer Device class identifier.

Authorization

Administrator or Key (ManageDeviceClass)

Request Body

In the request body, supply a DeviceClass resource.

Property Name Required Type Description
name No string Device class display name.
version No string Device class version.
isPermanent No boolean Indicates whether device class is permanent. Permanent device classes could not be modified by devices during registration.
offlineTimeout No integer If set, specifies inactivity timeout in seconds before the framework changes device status to 'Offline'. Device considered inactive when it's not persistently connected and does not send any notifications.
data No object Device class data, a JSON object with an arbitrary structure.
equipment No array A collection of associated equipment objects.
equipment[].name Yes string Equipment display name.
equipment[].code Yes string Equipment code. It's used to reference particular equipment and it should be unique within a device class.
equipment[].type Yes string Equipment type. An arbitrary string representing equipment capabilities.
equipment[].data No object Equipment data, a JSON object with an arbitrary structure.

Response

If successful, this method returns an empty response body.

DeviceClass: delete

Deletes an existing device class.

Request

HTTP Request

DELETE /device/class/{id}

Parameters

Parameter Name Required Type Description
id Yes integer Device class identifier.

Authorization

Administrator or Key (ManageDeviceClass)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns an empty response body.

DeviceCommand

Represents a device command, a unit of information sent to devices.

Methods

Method Authorization Uri Description
query User or Device or Key (GetDeviceCommand) GET /device/{deviceGuid}/command Queries device commands.
get User or Device or Key (GetDeviceCommand) GET /device/{deviceGuid}/command/{id} Gets information about device command.
insert User or Key (CreateDeviceCommand) POST /device/{deviceGuid}/command Creates new device command.
update User or Device or Key (UpdateDeviceCommand) PUT /device/{deviceGuid}/command/{id} Updates an existing device command.
poll User or Device or Key (GetDeviceCommand) GET /device/{deviceGuid}/command/poll

Polls new device commands.

This method returns all device commands that were created after specified timestamp.

In the case when no commands were found, the method blocks until new command is received. If no commands are received within the waitTimeout period, the server returns an empty response. In this case, to continue polling, the client should repeat the call with the same timestamp value.

wait User or Key (GetDeviceCommand) GET /device/{deviceGuid}/command/{id}/poll

Waits for a command to be processed.

This method returns a command only if it has been processed by a device.

In the case when command is not processed, the method blocks until device acknowledges command execution. If the command is not processed within the waitTimeout period, the server returns an empty response. In this case, to continue polling, the client should repeat the call.

pollMany User or Key (GetDeviceCommand) GET /device/command/poll

Polls new device commands.

This method returns all device commands that were created after specified timestamp.

In the case when no commands were found, the method blocks until new command is received. If no commands are received within the waitTimeout period, the server returns an empty response. In this case, to continue polling, the client should repeat the call with the same timestamp value.

Resource Representation

{
    "id": {integer},
    "timestamp": {datetime},
    "userId": {integer},
    "command": {string},
    "parameters": {object},
    "lifetime": {integer},
    "status": {string},
    "result": {object}
}
Property Name Type Description
id integer Command identifier.
timestamp datetime Command timestamp (UTC).
userId integer Associated user identifier.
command string Command name.
parameters object Command parameters, a JSON object with an arbitrary structure.
lifetime integer Command lifetime, a number of seconds until this command expires.
status string Command status, as reported by device or related infrastructure.
result object Command execution result, an optional value that could be provided by device.

DeviceCommand: query

Queries device commands.

Request

HTTP Request

GET /device/{deviceGuid}/command

Parameters

Parameter Name Required Type Description
deviceGuid Yes string Device unique identifier.
start No datetime Filter by command start timestamp (UTC).
end No datetime Filter by command end timestamp (UTC).
command No string Filter by command name.
status No string Filter by command status.
sortField No string Result list sort field. Available values are Timestamp (default), Command and Status.
sortOrder No string Result list sort order. Available values are ASC and DESC.
take No integer Number of records to take from the result list (default is 1000).
skip No integer Number of records to skip from the result list.

Authorization

User or Device or Key (GetDeviceCommand)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns array of DeviceCommand resources in the response body.

Property Name Type Description
id integer Command identifier.
timestamp datetime Command timestamp (UTC).
userId integer Associated user identifier.
command string Command name.
parameters object Command parameters, a JSON object with an arbitrary structure.
lifetime integer Command lifetime, a number of seconds until this command expires.
status string Command status, as reported by device or related infrastructure.
result object Command execution result, an optional value that could be provided by device.

DeviceCommand: get

Gets information about device command.

Request

HTTP Request

GET /device/{deviceGuid}/command/{id}

Parameters

Parameter Name Required Type Description
deviceGuid Yes string Device unique identifier.
id Yes integer Command identifier.

Authorization

User or Device or Key (GetDeviceCommand)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns a DeviceCommand resource in the response body.

Property Name Type Description
id integer Command identifier.
timestamp datetime Command timestamp (UTC).
userId integer Associated user identifier.
command string Command name.
parameters object Command parameters, a JSON object with an arbitrary structure.
lifetime integer Command lifetime, a number of seconds until this command expires.
status string Command status, as reported by device or related infrastructure.
result object Command execution result, an optional value that could be provided by device.

DeviceCommand: insert

Creates new device command.

Request

HTTP Request

POST /device/{deviceGuid}/command

Parameters

Parameter Name Required Type Description
deviceGuid Yes string Device unique identifier.

Authorization

User or Key (CreateDeviceCommand)

Request Body

In the request body, supply a DeviceCommand resource.

Property Name Required Type Description
command Yes string Command name.
parameters No object Command parameters, a JSON object with an arbitrary structure.
lifetime No integer Command lifetime, a number of seconds until this command expires.

Response

If successful, this method returns a DeviceCommand resource in the response body.

Property Name Type Description
id integer Command identifier.
timestamp datetime Command timestamp (UTC).
userId integer Associated user identifier.

DeviceCommand: update

Updates an existing device command.

Request

HTTP Request

PUT /device/{deviceGuid}/command/{id}

Parameters

Parameter Name Required Type Description
deviceGuid Yes string Device unique identifier.
id Yes integer Device command identifier.

Authorization

User or Device or Key (UpdateDeviceCommand)

Request Body

In the request body, supply a DeviceCommand resource.

Property Name Required Type Description
status No string Command status, as reported by device or related infrastructure.
result No object Command execution result, an optional value that could be provided by device.

Response

If successful, this method returns an empty response body.

DeviceCommand: poll

Polls new device commands.

This method returns all device commands that were created after specified timestamp.

In the case when no commands were found, the method blocks until new command is received. If no commands are received within the waitTimeout period, the server returns an empty response. In this case, to continue polling, the client should repeat the call with the same timestamp value.

Request

HTTP Request

GET /device/{deviceGuid}/command/poll?timestamp={timestamp}&names={names}&waitTimeout={waitTimeout}

Parameters

Parameter Name Required Type Description
deviceGuid Yes string Device unique identifier.
timestamp No datetime Timestamp of the last received command (UTC). If not specified, the server's timestamp is taken instead.
names No string Comma-separated list of commands names.
waitTimeout No integer Waiting timeout in seconds (default: 30 seconds, maximum: 60 seconds). Specify 0 to disable waiting.

Authorization

User or Device or Key (GetDeviceCommand)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns array of DeviceCommand resources in the response body.

Property Name Type Description
id integer Command identifier.
timestamp datetime Command timestamp (UTC).
userId integer Associated user identifier.
command string Command name.
parameters object Command parameters, a JSON object with an arbitrary structure.
lifetime integer Command lifetime, a number of seconds until this command expires.
status string Command status, as reported by device or related infrastructure.
result object Command execution result, an optional value that could be provided by device.

DeviceCommand: wait

Waits for a command to be processed.

This method returns a command only if it has been processed by a device.

In the case when command is not processed, the method blocks until device acknowledges command execution. If the command is not processed within the waitTimeout period, the server returns an empty response. In this case, to continue polling, the client should repeat the call.

Request

HTTP Request

GET /device/{deviceGuid}/command/{id}/poll?waitTimeout={waitTimeout}

Parameters

Parameter Name Required Type Description
deviceGuid Yes string Device unique identifier.
id Yes integer Command identifier.
waitTimeout No integer Waiting timeout in seconds (default: 30 seconds, maximum: 60 seconds). Specify 0 to disable waiting.

Authorization

User or Key (GetDeviceCommand)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns a DeviceCommand resource in the response body.

Property Name Type Description
id integer Command identifier.
timestamp datetime Command timestamp (UTC).
userId integer Associated user identifier.
command string Command name.
parameters object Command parameters, a JSON object with an arbitrary structure.
lifetime integer Command lifetime, a number of seconds until this command expires.
status string Command status, as reported by device or related infrastructure.
result object Command execution result, an optional value that could be provided by device.

DeviceCommand: pollMany

Polls new device commands.

This method returns all device commands that were created after specified timestamp.

In the case when no commands were found, the method blocks until new command is received. If no commands are received within the waitTimeout period, the server returns an empty response. In this case, to continue polling, the client should repeat the call with the same timestamp value.

Request

HTTP Request

GET /device/command/poll?deviceGuids={deviceGuids}&timestamp={timestamp}&names={names}&waitTimeout={waitTimeout}

Parameters

Parameter Name Required Type Description
deviceGuids No string Comma-separated list of device unique identifiers.
timestamp No datetime Timestamp of the last received command (UTC). If not specified, the server's timestamp is taken instead.
names No string Comma-separated list of commands names.
waitTimeout No integer Waiting timeout in seconds (default: 30 seconds, maximum: 60 seconds). Specify 0 to disable waiting.

Authorization

User or Key (GetDeviceCommand)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns array of the following resources in the response body.

Property Name Type Description
deviceGuid guid Associated device unique identifier.
command object DeviceCommand resource.
command.id integer Command identifier.
command.timestamp datetime Command timestamp (UTC).
command.userId integer Associated user identifier.
command.command string Command name.
command.parameters object Command parameters, a JSON object with an arbitrary structure.
command.lifetime integer Command lifetime, a number of seconds until this command expires.
command.status string Command status, as reported by device or related infrastructure.
command.result object Command execution result, an optional value that could be provided by device.

DeviceNotification

Represents a device notification, a unit of information dispatched from devices.

Methods

Method Authorization Uri Description
query User or Key (GetDeviceNotification) GET /device/{deviceGuid}/notification Queries device notifications.
get User or Key (GetDeviceNotification) GET /device/{deviceGuid}/notification/{id} Gets information about device notification.
insert User or Device or Key (CreateDeviceNotification) POST /device/{deviceGuid}/notification Creates new device notification.
poll User or Key (GetDeviceNotification) GET /device/{deviceGuid}/notification/poll

Polls new device notifications.

This method returns all device notifications that were created after specified timestamp.

In the case when no notifications were found, the method blocks until new notification is received. If no notifications are received within the waitTimeout period, the server returns an empty response. In this case, to continue polling, the client should repeat the call with the same timestamp value.

pollMany User or Key (GetDeviceNotification) GET /device/notification/poll

Polls new device notifications.

This method returns all device notifications that were created after specified timestamp.

In the case when no notifications were found, the method blocks until new notification is received. If no notifications are received within the waitTimeout period, the server returns an empty response. In this case, to continue polling, the client should repeat the call with the same timestamp value.

Resource Representation

{
    "id": {integer},
    "timestamp": {datetime},
    "notification": {string},
    "parameters": {object}
}
Property Name Type Description
id integer Notification identifier.
timestamp datetime Notification timestamp (UTC).
notification string Notification name.
parameters object Notification parameters, a JSON object with an arbitrary structure.

DeviceNotification: query

Queries device notifications.

Request

HTTP Request

GET /device/{deviceGuid}/notification

Parameters

Parameter Name Required Type Description
deviceGuid Yes string Device unique identifier.
start No datetime Filter by notification start timestamp (UTC).
end No datetime Filter by notification end timestamp (UTC).
notification No string Filter by notification name.
gridInterval No integer Filter notifications to retrieve maximum one notification of the same type within the specified grid interval (interval is measured in seconds).
sortField No string Result list sort field. Available values are Timestamp (default) and Notification.
sortOrder No string Result list sort order. Available values are ASC and DESC.
take No integer Number of records to take from the result list (default is 1000).
skip No integer Number of records to skip from the result list.

Authorization

User or Key (GetDeviceNotification)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns array of DeviceNotification resources in the response body.

Property Name Type Description
id integer Notification identifier.
timestamp datetime Notification timestamp (UTC).
notification string Notification name.
parameters object Notification parameters, a JSON object with an arbitrary structure.

DeviceNotification: get

Gets information about device notification.

Request

HTTP Request

GET /device/{deviceGuid}/notification/{id}

Parameters

Parameter Name Required Type Description
deviceGuid Yes string Device unique identifier.
id Yes integer Notification identifier.

Authorization

User or Key (GetDeviceNotification)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns a DeviceNotification resource in the response body.

Property Name Type Description
id integer Notification identifier.
timestamp datetime Notification timestamp (UTC).
notification string Notification name.
parameters object Notification parameters, a JSON object with an arbitrary structure.

DeviceNotification: insert

Creates new device notification.

Request

HTTP Request

POST /device/{deviceGuid}/notification

Parameters

Parameter Name Required Type Description
deviceGuid Yes string Device unique identifier.

Authorization

User or Device or Key (CreateDeviceNotification)

Request Body

In the request body, supply a DeviceNotification resource.

Property Name Required Type Description
notification Yes string Notification name.
parameters No object Notification parameters, a JSON object with an arbitrary structure.

Response

If successful, this method returns a DeviceNotification resource in the response body.

Property Name Type Description
id integer Notification identifier.
timestamp datetime Notification timestamp (UTC).

DeviceNotification: poll

Polls new device notifications.

This method returns all device notifications that were created after specified timestamp.

In the case when no notifications were found, the method blocks until new notification is received. If no notifications are received within the waitTimeout period, the server returns an empty response. In this case, to continue polling, the client should repeat the call with the same timestamp value.

Request

HTTP Request

GET /device/{deviceGuid}/notification/poll?timestamp={timestamp}&names={names}&waitTimeout={waitTimeout}

Parameters

Parameter Name Required Type Description
deviceGuid Yes string Device unique identifier.
timestamp No datetime Timestamp of the last received notification (UTC). If not specified, the server's timestamp is taken instead.
names No string Comma-separated list of notification names.
waitTimeout No integer Waiting timeout in seconds (default: 30 seconds, maximum: 60 seconds). Specify 0 to disable waiting.

Authorization

User or Key (GetDeviceNotification)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns array of DeviceNotification resources in the response body.

Property Name Type Description
id integer Notification identifier.
timestamp datetime Notification timestamp (UTC).
notification string Notification name.
parameters object Notification parameters, a JSON object with an arbitrary structure.

DeviceNotification: pollMany

Polls new device notifications.

This method returns all device notifications that were created after specified timestamp.

In the case when no notifications were found, the method blocks until new notification is received. If no notifications are received within the waitTimeout period, the server returns an empty response. In this case, to continue polling, the client should repeat the call with the same timestamp value.

Request

HTTP Request

GET /device/notification/poll?deviceGuids={deviceGuids}&timestamp={timestamp}&names={names}&waitTimeout={waitTimeout}

Parameters

Parameter Name Required Type Description
deviceGuids No string Comma-separated list of device unique identifiers.
timestamp No datetime Timestamp of the last received notification (UTC). If not specified, the server's timestamp is taken instead.
names No string Comma-separated list of notification names.
waitTimeout No integer Waiting timeout in seconds (default: 30 seconds, maximum: 60 seconds). Specify 0 to disable waiting.

Authorization

User or Key (GetDeviceNotification)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns array of the following resources in the response body.

Property Name Type Description
deviceGuid guid Associated device unique identifier.
notification object DeviceNotification resource.
notification.id integer Notification identifier.
notification.timestamp datetime Notification timestamp (UTC).
notification.notification string Notification name.
notification.parameters object Notification parameters, a JSON object with an arbitrary structure.

Network

Represents a network, an isolated area where devices reside.

Methods

Method Authorization Uri Description
list User or Key (GetNetwork) GET /network Gets list of device networks.

The result list is limited to networks the client has access to.

get User or Key (GetNetwork) GET /network/{id} Gets information about device network and its devices.
insert Administrator or Key (ManageNetwork) POST /network Creates new device network.
update Administrator or Key (ManageNetwork) PUT /network/{id} Updates an existing device network.
delete Administrator or Key (ManageNetwork) DELETE /network/{id} Deletes an existing device network.

Resource Representation

{
    "id": {integer},
    "key": {string},
    "name": {string},
    "description": {string}
}
Property Name Type Description
id integer Network identifier.
key string Optional key that is used to protect the network from unauthorized device registrations. When defined, devices will need to pass the key in order to register to the current network.
name string Network display name.
description string Network description.

Network: list

Gets list of device networks.

The result list is limited to networks the client has access to.

Request

HTTP Request

GET /network

Parameters

Parameter Name Required Type Description
name No string Filter by network name.
namePattern No string Filter by network name pattern.
sortField No string Result list sort field. Available values are ID and Name.
sortOrder No string Result list sort order. Available values are ASC and DESC.
take No integer Number of records to take from the result list.
skip No integer Number of records to skip from the result list.

Authorization

User or Key (GetNetwork)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns array of Network resources in the response body.

Property Name Type Description
id integer Network identifier.
key string Optional key that is used to protect the network from unauthorized device registrations. When defined, devices will need to pass the key in order to register to the current network.
name string Network display name.
description string Network description.

Network: get

Gets information about device network and its devices.

Request

HTTP Request

GET /network/{id}

Parameters

Parameter Name Required Type Description
id Yes integer Network identifier.

Authorization

User or Key (GetNetwork)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns a Network resource in the response body.

Property Name Type Description
id integer Network identifier.
key string Optional key that is used to protect the network from unauthorized device registrations. When defined, devices will need to pass the key in order to register to the current network.
name string Network display name.
description string Network description.
devices array Array of devices registered in the current network.
devices[].id string Device unique identifier.
devices[].name string Device display name.
devices[].status string Device operation status. The status is optional and it can be set to an arbitrary value, if applicable.

If device status monitoring feature is enabled, the framework will set status value to 'Offline' after defined period of inactivity.

devices[].data object Device data, a JSON object with an arbitrary structure.
devices[].deviceClass object Associated device class object.
devices[].deviceClass.id integer Device class identifier.
devices[].deviceClass.name string Device class display name.
devices[].deviceClass.version string Device class version.
devices[].deviceClass.isPermanent boolean Indicates whether device class is permanent. Permanent device classes could not be modified by devices during registration.
devices[].deviceClass.offlineTimeout integer If set, specifies inactivity timeout in seconds before the framework changes device status to 'Offline'. Device considered inactive when it's not persistently connected and does not send any notifications.
devices[].deviceClass.data object Device class data, a JSON object with an arbitrary structure.
devices[].deviceClass.equipment array A collection of associated equipment objects.
devices[].deviceClass.equipment[].id integer Equipment identifier.
devices[].deviceClass.equipment[].name string Equipment display name.
devices[].deviceClass.equipment[].code string Equipment code. It's used to reference particular equipment and it should be unique within a device class.
devices[].deviceClass.equipment[].type string Equipment type. An arbitrary string representing equipment capabilities.
devices[].deviceClass.equipment[].data object Equipment data, a JSON object with an arbitrary structure.

Network: insert

Creates new device network.

Request

HTTP Request

POST /network

Authorization

Administrator or Key (ManageNetwork)

Request Body

In the request body, supply a Network resource.

Property Name Required Type Description
key No string Optional key that is used to protect the network from unauthorized device registrations. When defined, devices will need to pass the key in order to register to the current network.
name Yes string Network display name.
description No string Network description.

Response

If successful, this method returns a Network resource in the response body.

Property Name Type Description
id integer Network identifier.

Network: update

Updates an existing device network.

Request

HTTP Request

PUT /network/{id}

Parameters

Parameter Name Required Type Description
id Yes integer Network identifier.

Authorization

Administrator or Key (ManageNetwork)

Request Body

In the request body, supply a Network resource.

Property Name Required Type Description
key No string Optional key that is used to protect the network from unauthorized device registrations. When defined, devices will need to pass the key in order to register to the current network.
name No string Network display name.
description No string Network description.

Response

If successful, this method returns an empty response body.

Network: delete

Deletes an existing device network.

Request

HTTP Request

DELETE /network/{id}

Parameters

Parameter Name Required Type Description
id Yes integer Network identifier.

Authorization

Administrator or Key (ManageNetwork)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns an empty response body.

OAuthClient

Represents a client with the access to the DeviceHive OAuth API.

Methods

Method Authorization Uri Description
list None GET /oauth/client Gets list of OAuth clients.
get None GET /oauth/client/{id} Gets information about OAuth client.
insert Administrator or Key (ManageOAuthClient) POST /oauth/client Creates new OAuth client.
update Administrator or Key (ManageOAuthClient) PUT /oauth/client/{id} Updates an existing OAuth client.
delete Administrator or Key (ManageOAuthClient) DELETE /oauth/client/{id} Deletes an existing OAuth client.

Resource Representation

{
    "id": {integer},
    "name": {string},
    "domain": {string},
    "subnet": {string},
    "redirectUri": {string},
    "oauthId": {string},
    "oauthSecret": {string}
}
Property Name Type Description
id integer Client identifier.
name string Client display name.
domain string Client domain allowed for API access.
subnet string Client IP subnet allowed for API access.
redirectUri string Client OAuth redirect URI.
oauthId string Client OAuth ID.
oauthSecret string Client OAuth secret.

OAuthClient: list

Gets list of OAuth clients.

Request

HTTP Request

GET /oauth/client

Parameters

Parameter Name Required Type Description
name No string Filter by client name.
namePattern No string Filter by client name pattern.
domain No string Filter by domain.
oauthId No string Filter by OAuth client ID.
sortField No string Result list sort field. Available values are ID, Name, Domain and OAuthID.
sortOrder No string Result list sort order. Available values are ASC and DESC.
take No integer Number of records to take from the result list.
skip No integer Number of records to skip from the result list.

Authorization

None

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns array of OAuthClient resources in the response body.

Property Name Type Description
id integer Client identifier.
name string Client display name.
domain string Client domain allowed for API access.
subnet string Client IP subnet allowed for API access.
redirectUri string Client OAuth redirect URI.
oauthId string Client OAuth ID.
oauthSecret string Client OAuth secret.

OAuthClient: get

Gets information about OAuth client.

Request

HTTP Request

GET /oauth/client/{id}

Parameters

Parameter Name Required Type Description
id Yes integer OAuth client identifier.

Authorization

None

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns an OAuthClient resource in the response body.

Property Name Type Description
id integer Client identifier.
name string Client display name.
domain string Client domain allowed for API access.
subnet string Client IP subnet allowed for API access.
redirectUri string Client OAuth redirect URI.
oauthId string Client OAuth ID.
oauthSecret string Client OAuth secret.

OAuthClient: insert

Creates new OAuth client.

Request

HTTP Request

POST /oauth/client

Authorization

Administrator or Key (ManageOAuthClient)

Request Body

In the request body, supply a OAuthClient resource.

Property Name Required Type Description
name Yes string Client display name.
domain Yes string Client domain allowed for API access.
subnet No string Client IP subnet allowed for API access.
redirectUri Yes string Client OAuth redirect URI.
oauthId Yes string Client OAuth ID.

Response

If successful, this method returns a OAuthClient resource in the response body.

Property Name Type Description
id integer Client identifier.
oauthSecret string Client OAuth secret.

OAuthClient: update

Updates an existing OAuth client.

Request

HTTP Request

PUT /oauth/client/{id}

Parameters

Parameter Name Required Type Description
id Yes integer OAuth client identifier.

Authorization

Administrator or Key (ManageOAuthClient)

Request Body

In the request body, supply a OAuthClient resource.

Property Name Required Type Description
name No string Client display name.
domain No string Client domain allowed for API access.
subnet No string Client IP subnet allowed for API access.
redirectUri No string Client OAuth redirect URI.
oauthId No string Client OAuth ID.

Response

If successful, this method returns an empty response body.

OAuthClient: delete

Deletes an existing OAuth client.

Request

HTTP Request

DELETE /oauth/client/{id}

Parameters

Parameter Name Required Type Description
id Yes integer OAuth client identifier.

Authorization

Administrator or Key (ManageOAuthClient)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns an empty response body.

OAuthGrant

Represents an OAuth permission grant.

Methods

Method Authorization Uri Description
list User or Key (ManageOAuthGrant) GET /user/{userId}/oauth/grant Gets list of OAuth grants.
get User or Key (ManageOAuthGrant) GET /user/{userId}/oauth/grant/{id} Gets information about OAuth grant.
insert User or Key (ManageOAuthGrant) POST /user/{userId}/oauth/grant Creates new OAuth grant.
update User or Key (ManageOAuthGrant) PUT /user/{userId}/oauth/grant/{id} Updates an existing OAuth grant.
delete User or Key (ManageOAuthGrant) DELETE /user/{userId}/oauth/grant/{id} Deletes an existing OAuth grant.

Resource Representation

{
    "id": {integer},
    "timestamp": {datetime},
    "authCode": {guid},
    "client": {
        "id": {integer},
        "name": {string},
        "domain": {string},
        "subnet": {string},
        "redirectUri": {string},
        "oauthId": {string},
        "oauthSecret": {string}
    },
    "accessKey": {
        "id": {integer},
        "type": {integer},
        "label": {string},
        "key": {string},
        "expirationDate": {datetime},
        "permissions": [
            {
                "domains": {array},
                "subnets": {array},
                "actions": {array},
                "networkIds": {array},
                "deviceGuids": {array}
            }
        ]
    },
    "type": {integer},
    "accessType": {integer},
    "redirectUri": {string},
    "scope": {string},
    "networkIds": {array}
}
Property Name Type Description
id integer OAuth grant identifier.
timestamp datetime OAuth grant timestamp.
authCode guid OAuth authorization code.
client object Associated OAuthClient object.
client.id integer Client identifier.
client.name string Client display name.
client.domain string Client domain allowed for API access.
client.subnet string Client IP subnet allowed for API access.
client.redirectUri string Client OAuth redirect URI.
client.oauthId string Client OAuth ID.
client.oauthSecret string Client OAuth secret.
accessKey object Associated AccessKey object.
accessKey.id integer Access key identifier.
accessKey.type integer Access key type. Available values:
  • 0: Default
  • 1: Session (with sliding expiration)
  • 2: OAuth (issued via OAuth2 token endpoint)
accessKey.label string Access key label.
accessKey.key string Access key value.
accessKey.expirationDate datetime Expiration date (UTC).
accessKey.permissions array A collection of associated permission objects.
accessKey.permissions[].domains array A collection of domains to which this permission applies. Only API requests from the specified domains will be authorized with this permission. Set to null to allow callees from any domain to make specified actions.
accessKey.permissions[].subnets array A collection of source IP addresses or subnets to which this permission applies. Only API requests from the specified addresses/subnets will be authorized with this permission. Set to null to allow any callees to make specified actions. Subnet format example: 12.12.12.12, or 12.12.12.0/24
accessKey.permissions[].actions array A collection of allowed actions. Available values:
  • GetNetwork: get information about network
  • GetDevice: get information about device and device class
  • GetDeviceState: get information about current device equipment state
  • GetDeviceNotification: get or subscribe to device notifications
  • GetDeviceCommand: get or subscribe to commands sent to device
  • RegisterDevice: register a device
  • CreateDeviceNotification: post notifications on behalf of device
  • CreateDeviceCommand: post commands to device
  • UpdateDeviceCommand: update status of commands on behalf of device
accessKey.permissions[].networkIds array A collection of identifiers of allowed networks. Only API requests for devices within the allowed networks will be authorized with this permission. Set to null to allow callees to access all networks permitted for the owner user.
accessKey.permissions[].deviceGuids array A collection of unique identifiers of allowed devices. Only API requests for allowed devices will be authorized with this permission. Set to null to allow callees to access all devices permitted for the owner user.
type integer OAuth grant type.
  • Code: Authorization Code grant
  • Token: Implicit grant
  • Password: Password Credentials grant
accessType integer Grant access type. Available values:
  • Online: Access is requested to a limited period of time
  • Offline: Assess is requested for an unlimited period of time
redirectUri string OAuth redirect URI specified during authorization.
scope string Requested OAuth scope. The scope should include a space-delimited list of required access key permissions.
networkIds array A collection of network identifiers requested for access. Set to null to request access for all accessible networks.

OAuthGrant: list

Gets list of OAuth grants.

Request

HTTP Request

GET /user/{userId}/oauth/grant

Parameters

Parameter Name Required Type Description
userId Yes integer User identifier. Use the 'current' keyword to list OAuth grants of the current user.
start No datetime Filter by grant start timestamp (UTC).
end No datetime Filter by grant end timestamp (UTC).
clientOAuthId No string Filter by OAuth client OAuth identifier.
type No integer Filter by OAuth grant type.
scope No string Filter by OAuth scope.
redirectUri No string Filter by OAuth redirect URI.
accessType No integer Filter by access type.
sortField No string Result list sort field. Available values are Timestamp (default).
sortOrder No string Result list sort order. Available values are ASC and DESC.
take No integer Number of records to take from the result list.
skip No integer Number of records to skip from the result list.

Authorization

User or Key (ManageOAuthGrant)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns array of OAuthGrant resources in the response body.

Property Name Type Description
id integer OAuth grant identifier.
timestamp datetime OAuth grant timestamp.
authCode guid OAuth authorization code.
client object Associated OAuthClient object.
client.id integer Client identifier.
client.name string Client display name.
client.domain string Client domain allowed for API access.
client.subnet string Client IP subnet allowed for API access.
client.redirectUri string Client OAuth redirect URI.
client.oauthId string Client OAuth ID.
client.oauthSecret string Client OAuth secret.
accessKey object Associated AccessKey object.
accessKey.id integer Access key identifier.
accessKey.type integer Access key type. Available values:
  • 0: Default
  • 1: Session (with sliding expiration)
  • 2: OAuth (issued via OAuth2 token endpoint)
accessKey.label string Access key label.
accessKey.key string Access key value.
accessKey.expirationDate datetime Expiration date (UTC).
accessKey.permissions array A collection of associated permission objects.
accessKey.permissions[].domains array A collection of domains to which this permission applies. Only API requests from the specified domains will be authorized with this permission. Set to null to allow callees from any domain to make specified actions.
accessKey.permissions[].subnets array A collection of source IP addresses or subnets to which this permission applies. Only API requests from the specified addresses/subnets will be authorized with this permission. Set to null to allow any callees to make specified actions. Subnet format example: 12.12.12.12, or 12.12.12.0/24
accessKey.permissions[].actions array A collection of allowed actions. Available values:
  • GetNetwork: get information about network
  • GetDevice: get information about device and device class
  • GetDeviceState: get information about current device equipment state
  • GetDeviceNotification: get or subscribe to device notifications
  • GetDeviceCommand: get or subscribe to commands sent to device
  • RegisterDevice: register a device
  • CreateDeviceNotification: post notifications on behalf of device
  • CreateDeviceCommand: post commands to device
  • UpdateDeviceCommand: update status of commands on behalf of device
accessKey.permissions[].networkIds array A collection of identifiers of allowed networks. Only API requests for devices within the allowed networks will be authorized with this permission. Set to null to allow callees to access all networks permitted for the owner user.
accessKey.permissions[].deviceGuids array A collection of unique identifiers of allowed devices. Only API requests for allowed devices will be authorized with this permission. Set to null to allow callees to access all devices permitted for the owner user.
type integer OAuth grant type.
  • Code: Authorization Code grant
  • Token: Implicit grant
  • Password: Password Credentials grant
accessType integer Grant access type. Available values:
  • Online: Access is requested to a limited period of time
  • Offline: Assess is requested for an unlimited period of time
redirectUri string OAuth redirect URI specified during authorization.
scope string Requested OAuth scope. The scope should include a space-delimited list of required access key permissions.
networkIds array A collection of network identifiers requested for access. Set to null to request access for all accessible networks.

OAuthGrant: get

Gets information about OAuth grant.

Request

HTTP Request

GET /user/{userId}/oauth/grant/{id}

Parameters

Parameter Name Required Type Description
userId Yes integer User identifier. Use the 'current' keyword to get OAuth grant of the current user.
id Yes integer OAuth grant identifier.

Authorization

User or Key (ManageOAuthGrant)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns a OAuthGrant resource in the response body.

Property Name Type Description
id integer OAuth grant identifier.
timestamp datetime OAuth grant timestamp.
authCode guid OAuth authorization code.
client object Associated OAuthClient object.
client.id integer Client identifier.
client.name string Client display name.
client.domain string Client domain allowed for API access.
client.subnet string Client IP subnet allowed for API access.
client.redirectUri string Client OAuth redirect URI.
client.oauthId string Client OAuth ID.
client.oauthSecret string Client OAuth secret.
accessKey object Associated AccessKey object.
accessKey.id integer Access key identifier.
accessKey.type integer Access key type. Available values:
  • 0: Default
  • 1: Session (with sliding expiration)
  • 2: OAuth (issued via OAuth2 token endpoint)
accessKey.label string Access key label.
accessKey.key string Access key value.
accessKey.expirationDate datetime Expiration date (UTC).
accessKey.permissions array A collection of associated permission objects.
accessKey.permissions[].domains array A collection of domains to which this permission applies. Only API requests from the specified domains will be authorized with this permission. Set to null to allow callees from any domain to make specified actions.
accessKey.permissions[].subnets array A collection of source IP addresses or subnets to which this permission applies. Only API requests from the specified addresses/subnets will be authorized with this permission. Set to null to allow any callees to make specified actions. Subnet format example: 12.12.12.12, or 12.12.12.0/24
accessKey.permissions[].actions array A collection of allowed actions. Available values:
  • GetNetwork: get information about network
  • GetDevice: get information about device and device class
  • GetDeviceState: get information about current device equipment state
  • GetDeviceNotification: get or subscribe to device notifications
  • GetDeviceCommand: get or subscribe to commands sent to device
  • RegisterDevice: register a device
  • CreateDeviceNotification: post notifications on behalf of device
  • CreateDeviceCommand: post commands to device
  • UpdateDeviceCommand: update status of commands on behalf of device
accessKey.permissions[].networkIds array A collection of identifiers of allowed networks. Only API requests for devices within the allowed networks will be authorized with this permission. Set to null to allow callees to access all networks permitted for the owner user.
accessKey.permissions[].deviceGuids array A collection of unique identifiers of allowed devices. Only API requests for allowed devices will be authorized with this permission. Set to null to allow callees to access all devices permitted for the owner user.
type integer OAuth grant type.
  • Code: Authorization Code grant
  • Token: Implicit grant
  • Password: Password Credentials grant
accessType integer Grant access type. Available values:
  • Online: Access is requested to a limited period of time
  • Offline: Assess is requested for an unlimited period of time
redirectUri string OAuth redirect URI specified during authorization.
scope string Requested OAuth scope. The scope should include a space-delimited list of required access key permissions.
networkIds array A collection of network identifiers requested for access. Set to null to request access for all accessible networks.

OAuthGrant: insert

Creates new OAuth grant.

Request

HTTP Request

POST /user/{userId}/oauth/grant

Parameters

Parameter Name Required Type Description
userId Yes integer User identifier. Use the 'current' keyword to create OAuth grant for the current user.

Authorization

User or Key (ManageOAuthGrant)

Request Body

In the request body, supply a OAuthGrant resource.

Property Name Required Type Description
client Yes object A OAuthClient object which includes oauthId property to match.
client.oauthId Yes string Client OAuth identifier.
type Yes integer OAuth grant type.
  • Code: Authorization Code grant
  • Token: Implicit grant
  • Password: Password Credentials grant
accessType No integer Grant access type. Available values:
  • Online: Access is requested to a limited period of time
  • Offline: Assess is requested for an unlimited period of time
redirectUri Yes string OAuth redirect URI specified during authorization.
scope Yes string Requested OAuth scope. The scope should include a space-delimited list of required access key permissions.
networkIds No array A collection of network identifiers requested for access. Set to null to request access for all accessible networks.

Response

If successful, this method returns a OAuthGrant resource in the response body.

Property Name Type Description
id integer OAuth grant identifier.
timestamp datetime OAuth grant timestamp.
authCode guid OAuth authorization code.
accessKey object Associated AccessKey object.
accessKey.id integer Access key identifier.
accessKey.key string Access key value.

OAuthGrant: update

Updates an existing OAuth grant.

Request

HTTP Request

PUT /user/{userId}/oauth/grant/{id}

Parameters

Parameter Name Required Type Description
userId Yes integer User identifier. Use the 'current' keyword to update OAuth grant of the current user.
id Yes integer OAuth grant identifier.

Authorization

User or Key (ManageOAuthGrant)

Request Body

In the request body, supply a OAuthGrant resource.

Property Name Required Type Description
client No object A OAuthClient object which includes oauthId property to match.
client.oauthId Yes string Client OAuth identifier.
type No integer OAuth grant type.
  • Code: Authorization Code grant
  • Token: Implicit grant
  • Password: Password Credentials grant
accessType No integer Grant access type. Available values:
  • Online: Access is requested to a limited period of time
  • Offline: Assess is requested for an unlimited period of time
redirectUri No string OAuth redirect URI specified during authorization.
scope No string Requested OAuth scope. The scope should include a space-delimited list of required access key permissions.
networkIds No array A collection of network identifiers requested for access. Set to null to request access for all accessible networks.

Response

If successful, this method returns a OAuthGrant resource in the response body.

Property Name Type Description
id integer OAuth grant identifier.
timestamp datetime OAuth grant timestamp.
authCode guid OAuth authorization code.
accessKey object Associated AccessKey object.
accessKey.id integer Access key identifier.
accessKey.key string Access key value.

OAuthGrant: delete

Deletes an existing OAuth grant.

Request

HTTP Request

DELETE /user/{userId}/oauth/grant/{id}

Parameters

Parameter Name Required Type Description
userId Yes integer User identifier. Use the 'current' keyword to delete OAuth grant of the current user.
id Yes integer OAuth grant identifier.

Authorization

User or Key (ManageOAuthGrant)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns an empty response body.

User

Represents a user to this API.

Methods

Method Authorization Uri Description
list Administrator or Key (ManageUser) GET /user Gets list of users.
get User or Key (GetCurrentUser) GET /user/{id} Gets information about user and its assigned networks.

Only administrators are allowed to get information about any user. User-level accounts can only retrieve information about themselves.

insert Administrator or Key (ManageUser) POST /user Creates new user.
update User or Key (UpdateCurrentUser) PUT /user/{id} Updates an existing user.

Only administrators are allowed to update any property of any user. User-level accounts can only change their own password in case:

  • They already have a password.
  • They provide a valid current password in the 'oldPassword' property.
delete Administrator or Key (ManageUser) DELETE /user/{id} Deletes an existing user.
getNetwork Administrator or Key (ManageUser) GET /user/{id}/network/{networkId} Gets information about user/network association.
assignNetwork Administrator or Key (ManageUser) PUT /user/{id}/network/{networkId} Associates network with the user.
unassignNetwork Administrator or Key (ManageUser) DELETE /user/{id}/network/{networkId} Removes association between network and user.

Resource Representation

{
    "id": {integer},
    "login": {string},
    "facebookLogin": {string},
    "googleLogin": {string},
    "githubLogin": {string},
    "role": {integer},
    "status": {integer},
    "lastLogin": {datetime}
}
Property Name Type Description
id integer User identifier.
login string User login using during authentication.
facebookLogin string User Facebook login (for OAuth authentication).
googleLogin string User Google login (for OAuth authentication).
githubLogin string User Github login (for OAuth authentication).
role integer User role. Available values:
  • 0: Administrator role
  • 1: Client role
status integer User status. Available values:
  • 0: The user is active
  • 1: The user has been locked out due to invalid login attempts
  • 2: The user has been disabled
  • 3: The user has been deleted
lastLogin datetime User last login timestamp (UTC).

User: list

Gets list of users.

Request

HTTP Request

GET /user

Parameters

Parameter Name Required Type Description
login No string Filter by user login.
loginPattern No string Filter by user login pattern.
role No integer Filter by user role. 0 is Administrator, 1 is Client.
status No integer Filter by user status. 0 is Active, 1 is Locked Out, 2 is Disabled.
sortField No string Result list sort field. Available values are ID and Login.
sortOrder No string Result list sort order. Available values are ASC and DESC.
take No integer Number of records to take from the result list.
skip No integer Number of records to skip from the result list.

Authorization

Administrator or Key (ManageUser)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns array of User resources in the response body.

Property Name Type Description
id integer User identifier.
login string User login using during authentication.
facebookLogin string User Facebook login (for OAuth authentication).
googleLogin string User Google login (for OAuth authentication).
githubLogin string User Github login (for OAuth authentication).
role integer User role. Available values:
  • 0: Administrator role
  • 1: Client role
status integer User status. Available values:
  • 0: The user is active
  • 1: The user has been locked out due to invalid login attempts
  • 2: The user has been disabled
  • 3: The user has been deleted
lastLogin datetime User last login timestamp (UTC).

User: get

Gets information about user and its assigned networks.

Only administrators are allowed to get information about any user. User-level accounts can only retrieve information about themselves.

Request

HTTP Request

GET /user/{id}

Parameters

Parameter Name Required Type Description
id Yes integer User identifier. Use the 'current' keyword to get information about the current user.

Authorization

User or Key (GetCurrentUser)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns a User resource in the response body.

Property Name Type Description
id integer User identifier.
login string User login using during authentication.
facebookLogin string User Facebook login (for OAuth authentication).
googleLogin string User Google login (for OAuth authentication).
githubLogin string User Github login (for OAuth authentication).
role integer User role. Available values:
  • 0: Administrator role
  • 1: Client role
status integer User status. Available values:
  • 0: The user is active
  • 1: The user has been locked out due to invalid login attempts
  • 2: The user has been disabled
  • 3: The user has been deleted
lastLogin datetime User last login timestamp (UTC).
networks array Array of networks associated with the user
networks[].network object Associated network object.
networks[].network.id integer Network identifier.
networks[].network.key string Optional key that is used to protect the network from unauthorized device registrations. When defined, devices will need to pass the key in order to register to the current network.
networks[].network.name string Network display name.
networks[].network.description string Network description.

User: insert

Creates new user.

Request

HTTP Request

POST /user

Authorization

Administrator or Key (ManageUser)

Request Body

In the request body, supply a User resource.

Property Name Required Type Description
login Yes string User login using during authentication.
facebookLogin No string User Facebook login (for OAuth authentication).
googleLogin No string User Google login (for OAuth authentication).
githubLogin No string User Github login (for OAuth authentication).
role Yes integer User role. Available values:
  • 0: Administrator role
  • 1: Client role
status Yes integer User status. Available values:
  • 0: The user is active
  • 1: The user has been locked out due to invalid login attempts
  • 2: The user has been disabled
  • 3: The user has been deleted
password Yes string User password

Response

If successful, this method returns a User resource in the response body.

Property Name Type Description
id integer User identifier.
lastLogin datetime User last login timestamp (UTC).

User: update

Updates an existing user.

Only administrators are allowed to update any property of any user. User-level accounts can only change their own password in case:

  • They already have a password.
  • They provide a valid current password in the 'oldPassword' property.

Request

HTTP Request

PUT /user/{id}

Parameters

Parameter Name Required Type Description
id Yes integer User identifier. Use the 'current' keyword to update information of the current user.

Authorization

User or Key (UpdateCurrentUser)

Request Body

In the request body, supply a User resource.

Property Name Required Type Description
login No string User login using during authentication.
facebookLogin No string User Facebook login (for OAuth authentication).
googleLogin No string User Google login (for OAuth authentication).
githubLogin No string User Github login (for OAuth authentication).
role No integer User role. Available values:
  • 0: Administrator role
  • 1: Client role
status No integer User status. Available values:
  • 0: The user is active
  • 1: The user has been locked out due to invalid login attempts
  • 2: The user has been disabled
  • 3: The user has been deleted
password No string User new password
oldPassword No string User current password (for non-administrative password changing functionality only)

Response

If successful, this method returns an empty response body.

User: delete

Deletes an existing user.

Request

HTTP Request

DELETE /user/{id}

Parameters

Parameter Name Required Type Description
id Yes integer User identifier.

Authorization

Administrator or Key (ManageUser)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns an empty response body.

User: getNetwork

Gets information about user/network association.

Request

HTTP Request

GET /user/{id}/network/{networkId}

Parameters

Parameter Name Required Type Description
id Yes integer User identifier.
networkId Yes integer Network identifier.

Authorization

Administrator or Key (ManageUser)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns the following structure in the response body.

Property Name Type Description
network object Associated network object.
network.id integer Network identifier.
network.key string Optional key that is used to protect the network from unauthorized device registrations. When defined, devices will need to pass the key in order to register to the current network.
network.name string Network display name.
network.description string Network description.

User: assignNetwork

Associates network with the user.

Request

HTTP Request

PUT /user/{id}/network/{networkId}

Parameters

Parameter Name Required Type Description
id Yes integer User identifier.
networkId Yes integer Network identifier.

Authorization

Administrator or Key (ManageUser)

Request Body

In the request body, supply the empty object.

Response

If successful, this method returns an empty response body.

User: unassignNetwork

Removes association between network and user.

Request

HTTP Request

DELETE /user/{id}/network/{networkId}

Parameters

Parameter Name Required Type Description
id Yes integer User identifier.
networkId Yes integer Network identifier.

Authorization

Administrator or Key (ManageUser)

Request Body

Do not supply a request body with this method.

Response

If successful, this method returns an empty response body.

Client

The service allows clients to exchange messages with the DeviceHive server using a single persistent connection.

After connection is eshtablished, clients need to authenticate using their login and password or access key, and then start sending commands to devices using the command/insert message. As soon as a command is processed by a device, the server sends the command/update message.

Clients may also subscribe to device notifications using the notification/subscribe message and then start receiving server-originated messages about new device notifications.

WebSocket Handshake URI

GET /client

Messages

Message Originator Authorization Description
authenticate Client None Authenticates a client. Either login and password or accessKey parameters must be passed.
command/insert Client User or Key (CreateDeviceCommand) Creates new device command.
command/subscribe Client User or Key (GetDeviceCommand) Subscribes to device commands. After subscription is completed, the server will start to send command/insert messages to the connected user.
command/unsubscribe Client User or Key (GetDeviceCommand) Unsubscribes from device commands.
command/update Client User or Key (UpdateDeviceCommand) Updates an existing device command on behalf of device.
notification/insert Client User or Key (CreateDeviceNotification) Creates new device notification on behalf of device.
notification/subscribe Client User or Key (GetDeviceNotification) Subscribes to device notifications. After subscription is completed, the server will start to send notification/insert messages to the connected user.
notification/unsubscribe Client User or Key (GetDeviceNotification) Unsubscribes from device notifications.
server/info Client None Gets meta-information about the current API.
srv: command/insert Server n/a Notifies the user about new device command.
srv: command/update Server n/a Notifies the user about a command has been processed by a device. These messages are sent only for commands created by the current user within the current connection.
srv: notification/insert Server n/a Notifies the user about new device notification.

Client: authenticate

Authenticates a client. Either login and password or accessKey parameters must be passed.

Request Message

Authorization

None

Message Representation

{
    "action": {string},
    "requestId": {object},
    "login": {string},
    "password": {string},
    "accessKey": {string}
}

Message Parameters

Property Name Required Type Description
action Yes string Action name: authenticate
requestId No object Request unique identifier, will be passed back in the response message.
login No string User login.
password No string User password.
accessKey No string User access key.

Response Message

Message Representation

{
    "action": {string},
    "status": {string},
    "requestId": {object}
}

Message Parameters

Property Name Type Description
action string Action name: authenticate
status string Operation execution status (success or error).
requestId object Request unique identifier as specified in the request message.

Client: command/insert

Creates new device command.

Request Message

Authorization

User or Key (CreateDeviceCommand)

Message Representation

{
    "action": {string},
    "requestId": {object},
    "deviceGuid": {string},
    "command": {
        "command": {string},
        "parameters": {object},
        "lifetime": {integer},
        "status": {string},
        "result": {object}
    }
}

Message Parameters

Property Name Required Type Description
action Yes string Action name: command/insert
requestId No object Request unique identifier, will be passed back in the response message.
deviceGuid Yes string Target device unique identifier.
command Yes object A DeviceCommand resource to create.
command.command Yes string Command name.
command.parameters No object Command parameters, a JSON object with an arbitrary structure.
command.lifetime No integer Command lifetime, a number of seconds until this command expires.
command.status No string Command status, as reported by device or related infrastructure.
command.result No object Command execution result, an optional value that could be provided by device.

Response Message

Message Representation

{
    "action": {string},
    "status": {string},
    "requestId": {object},
    "command": {
        "id": {integer},
        "timestamp": {datetime},
        "userId": {integer}
    }
}

Message Parameters

Property Name Type Description
action string Action name: command/insert
status string Operation execution status (success or error).
requestId object Request unique identifier as specified in the request message.
command object An inserted DeviceCommand resource.
command.id integer Command identifier.
command.timestamp datetime Command timestamp (UTC).
command.userId integer Associated user identifier.

Client: command/subscribe

Subscribes to device commands. After subscription is completed, the server will start to send command/insert messages to the connected user.

Request Message

Authorization

User or Key (GetDeviceCommand)

Message Representation

{
    "action": {string},
    "requestId": {object},
    "timestamp": {datetime},
    "deviceGuids": {array},
    "names": {array}
}

Message Parameters

Property Name Required Type Description
action Yes string Action name: command/subscribe
requestId No object Request unique identifier, will be passed back in the response message.
timestamp No datetime Timestamp of the last received command (UTC). If not specified, the server's timestamp is taken instead.
deviceGuids No array Array of device unique identifiers to subscribe to. If not specified, the subscription is made to all accessible devices.
names No array Array of command names to subscribe to.

Response Message

Message Representation

{
    "action": {string},
    "status": {string},
    "requestId": {object},
    "subscriptionId": {guid}
}

Message Parameters

Property Name Type Description
action string Action name: command/subscribe
status string Operation execution status (success or error).
requestId object Request unique identifier as specified in the request message.
subscriptionId guid A unique identifier of the subscription made.

Client: command/unsubscribe

Unsubscribes from device commands.

Request Message

Authorization

User or Key (GetDeviceCommand)

Message Representation

{
    "action": {string},
    "requestId": {object},
    "subscriptionId": {guid}
}

Message Parameters

Property Name Required Type Description
action Yes string Action name: command/unsubscribe
requestId No object Request unique identifier, will be passed back in the response message.
subscriptionId Yes guid An identifier of the previously made subscription to unsubscribe from.

Response Message

Message Representation

{
    "action": {string},
    "status": {string},
    "requestId": {object}
}

Message Parameters

Property Name Type Description
action string Action name: command/unsubscribe
status string Operation execution status (success or error).
requestId object Request unique identifier as specified in the request message.

Client: command/update

Updates an existing device command on behalf of device.

Request Message

Authorization

User or Key (UpdateDeviceCommand)

Message Representation

{
    "action": {string},
    "requestId": {object},
    "deviceGuid": {string},
    "commandId": {integer},
    "command": {
        "command": {string},
        "parameters": {object},
        "lifetime": {integer},
        "status": {string},
        "result": {object}
    }
}

Message Parameters

Property Name Required Type Description
action Yes string Action name: command/update
requestId No object Request unique identifier, will be passed back in the response message.
deviceGuid Yes string Device unique identifier.
commandId Yes integer Device command identifier.
command Yes object A DeviceCommand resource to update.
command.command No string Command name.
command.parameters No object Command parameters, a JSON object with an arbitrary structure.
command.lifetime No integer Command lifetime, a number of seconds until this command expires.
command.status No string Command status, as reported by device or related infrastructure.
command.result No object Command execution result, an optional value that could be provided by device.

Response Message

Message Representation

{
    "action": {string},
    "status": {string},
    "requestId": {object}
}

Message Parameters

Property Name Type Description
action string Action name: command/update
status string Operation execution status (success or error).
requestId object Request unique identifier as specified in the request message.

Client: notification/insert

Creates new device notification on behalf of device.

Request Message

Authorization

User or Key (CreateDeviceNotification)

Message Representation

{
    "action": {string},
    "requestId": {object},
    "deviceGuid": {string},
    "notification": {
        "notification": {string},
        "parameters": {object}
    }
}

Message Parameters

Property Name Required Type Description
action Yes string Action name: notification/insert
requestId No object Request unique identifier, will be passed back in the response message.
deviceGuid Yes string Device unique identifier.
notification Yes object A DeviceNotification resource to create.
notification.notification Yes string Notification name.
notification.parameters No object Notification parameters, a JSON object with an arbitrary structure.

Response Message

Message Representation

{
    "action": {string},
    "status": {string},
    "requestId": {object},
    "notification": {
        "id": {integer},
        "timestamp": {datetime}
    }
}

Message Parameters

Property Name Type Description
action string Action name: notification/insert
status string Operation execution status (success or error).
requestId object Request unique identifier as specified in the request message.
notification object An inserted DeviceNotification resource.
notification.id integer Notification identifier.
notification.timestamp datetime Notification timestamp (UTC).

Client: notification/subscribe

Subscribes to device notifications. After subscription is completed, the server will start to send notification/insert messages to the connected user.

Request Message

Authorization

User or Key (GetDeviceNotification)

Message Representation

{
    "action": {string},
    "requestId": {object},
    "timestamp": {datetime},
    "deviceGuids": {array},
    "names": {array}
}

Message Parameters

Property Name Required Type Description
action Yes string Action name: notification/subscribe
requestId No object Request unique identifier, will be passed back in the response message.
timestamp No datetime Timestamp of the last received notification (UTC). If not specified, the server's timestamp is taken instead.
deviceGuids No array Array of device unique identifiers to subscribe to. If not specified, the subscription is made to all accessible devices.
names No array Array of notification names to subscribe to.

Response Message

Message Representation

{
    "action": {string},
    "status": {string},
    "requestId": {object},
    "subscriptionId": {guid}
}

Message Parameters

Property Name Type Description
action string Action name: notification/subscribe
status string Operation execution status (success or error).
requestId object Request unique identifier as specified in the request message.
subscriptionId guid A unique identifier of the subscription made.

Client: notification/unsubscribe

Unsubscribes from device notifications.

Request Message

Authorization

User or Key (GetDeviceNotification)

Message Representation

{
    "action": {string},
    "requestId": {object},
    "subscriptionId": {guid}
}

Message Parameters

Property Name Required Type Description
action Yes string Action name: notification/unsubscribe
requestId No object Request unique identifier, will be passed back in the response message.
subscriptionId Yes guid An identifier of the previously made subscription to unsubscribe from.

Response Message

Message Representation

{
    "action": {string},
    "status": {string},
    "requestId": {object}
}

Message Parameters

Property Name Type Description
action string Action name: notification/unsubscribe
status string Operation execution status (success or error).
requestId object Request unique identifier as specified in the request message.

Client: server/info

Gets meta-information about the current API.

Request Message

Authorization

None

Message Representation

{
    "action": {string},
    "requestId": {object}
}

Message Parameters

Property Name Required Type Description
action Yes string Action name: server/info
requestId No object Request unique identifier, will be passed back in the response message.

Response Message

Message Representation

{
    "action": {string},
    "status": {string},
    "requestId": {object},
    "info": {
        "apiVersion": {string},
        "serverTimestamp": {datetime},
        "restServerUrl": {string}
    }
}

Message Parameters

Property Name Type Description
action string Action name: server/info
status string Operation execution status (success or error).
requestId object Request unique identifier as specified in the request message.
info object The ApiInfo resource.
info.apiVersion string API version.
info.serverTimestamp datetime Current server timestamp.
info.restServerUrl string REST server URL.

Client: srv: command/insert

Notifies the user about new device command.

Server Message

Message Representation

{
    "action": {string},
    "subscriptionId": {guid},
    "deviceGuid": {string},
    "command": {
        "id": {integer},
        "timestamp": {datetime},
        "userId": {integer},
        "command": {string},
        "parameters": {object},
        "lifetime": {integer},
        "status": {string},
        "result": {object}
    }
}

Message Parameters

Property Name Type Description
action string Action name: command/insert
subscriptionId guid Identifier of the associated subscription.
deviceGuid string Device unique identifier.
command object A DeviceCommand resource representing the command.
command.id integer Command identifier.
command.timestamp datetime Command timestamp (UTC).
command.userId integer Associated user identifier.
command.command string Command name.
command.parameters object Command parameters, a JSON object with an arbitrary structure.
command.lifetime integer Command lifetime, a number of seconds until this command expires.
command.status string Command status, as reported by device or related infrastructure.
command.result object Command execution result, an optional value that could be provided by device.

Client: srv: command/update

Notifies the user about a command has been processed by a device. These messages are sent only for commands created by the current user within the current connection.

Server Message

Message Representation

{
    "action": {string},
    "command": {
        "id": {integer},
        "timestamp": {datetime},
        "userId": {integer},
        "command": {string},
        "parameters": {object},
        "lifetime": {integer},
        "status": {string},
        "result": {object}
    }
}

Message Parameters

Property Name Type Description
action string Action name: command/update
command object A DeviceCommand resource representing the processed command.
command.id integer Command identifier.
command.timestamp datetime Command timestamp (UTC).
command.userId integer Associated user identifier.
command.command string Command name.
command.parameters object Command parameters, a JSON object with an arbitrary structure.
command.lifetime integer Command lifetime, a number of seconds until this command expires.
command.status string Command status, as reported by device or related infrastructure.
command.result object Command execution result, an optional value that could be provided by device.

Client: srv: notification/insert

Notifies the user about new device notification.

Server Message

Message Representation

{
    "action": {string},
    "subscriptionId": {guid},
    "deviceGuid": {string},
    "notification": {
        "id": {integer},
        "timestamp": {datetime},
        "notification": {string},
        "parameters": {object}
    }
}

Message Parameters

Property Name Type Description
action string Action name: notification/insert
subscriptionId guid Identifier of the associated subscription.
deviceGuid string Device unique identifier.
notification object A DeviceNotification resource representing the notification.
notification.id integer Notification identifier.
notification.timestamp datetime Notification timestamp (UTC).
notification.notification string Notification name.
notification.parameters object Notification parameters, a JSON object with an arbitrary structure.

Device

The service allows devices to exchange messages with the DeviceHive server using a single persistent connection.

After connection is eshtablished, devices need to register using the device/save message, perform authentication and then start sending notifications using the notification/insert message.

Devices may also subscribe to commands using the command/subscrive message and then start receiving server-originated messages about new commands.

It is also possible not to authenticate as concrete device, but rather send device identifier and key in each request. That scenario is common for gateways which typically proxy multiple devices and use a single connection to the server.

WebSocket Handshake URI

GET /device

Messages

Message Originator Authorization Description
authenticate Device None Authenticates a device. After successful authentication, all subsequent messages may exclude deviceId and deviceKey parameters.
command/subscribe Device Device Subscribes the device to commands. After subscription is completed, the server will start to send command/insert messages to the connected device.
command/unsubscribe Device Device Unsubscribes the device from commands.
command/update Device Device Updates an existing device command.
device/get Device Device Gets information about the current device.
device/save Device Device Registers or updates a device.
notification/insert Device Device Creates new device notification.
server/info Device None Gets meta-information of the current API.
srv: command/insert Server n/a Notifies the device about new command.

Device: authenticate

Authenticates a device. After successful authentication, all subsequent messages may exclude deviceId and deviceKey parameters.

Request Message

Authorization

None

Message Representation

{
    "action": {string},
    "requestId": {object},
    "deviceId": {string},
    "deviceKey": {string}
}

Message Parameters

Property Name Required Type Description
action Yes string Action name: authenticate
requestId No object Request unique identifier, will be passed back in the response message.
deviceId Yes string Device unique identifier.
deviceKey Yes string Device authentication key.

Server Message

Message Representation

{
    "action": {string},
    "status": {string},
    "requestId": {object}
}

Message Parameters

Property Name Type Description
action string Action name: authenticate
status string Operation execution status (success or error).
requestId object Request unique identifier as specified in the request message.

Device: command/subscribe

Subscribes the device to commands. After subscription is completed, the server will start to send command/insert messages to the connected device.

Request Message

Authorization

Device

Message Representation

{
    "action": {string},
    "requestId": {object},
    "deviceId": {string},
    "deviceKey": {string},
    "timestamp": {datetime}
}

Message Parameters

Property Name Required Type Description
action Yes string Action name: command/subscribe
requestId No object Request unique identifier, will be passed back in the response message.
deviceId No string Device unique identifier (specify if not authenticated).
deviceKey No string Device authentication key (specify if not authenticated).
timestamp No datetime Timestamp of the last received command (UTC). If not specified, the server's timestamp is taken instead.

Server Message

Message Representation

{
    "action": {string},
    "status": {string},
    "requestId": {object}
}

Message Parameters

Property Name Type Description
action string Action name: command/subscribe
status string Operation execution status (success or error).
requestId object Request unique identifier as specified in the request message.

Device: command/unsubscribe

Unsubscribes the device from commands.

Request Message

Authorization

Device

Message Representation

{
    "action": {string},
    "requestId": {object},
    "deviceId": {string},
    "deviceKey": {string}
}

Message Parameters

Property Name Required Type Description
action Yes string Action name: command/unsubscribe
requestId No object Request unique identifier, will be passed back in the response message.
deviceId No string Device unique identifier (specify if not authenticated).
deviceKey No string Device authentication key (specify if not authenticated).

Server Message

Message Representation

{
    "action": {string},
    "status": {string},
    "requestId": {object}
}

Message Parameters

Property Name Type Description
action string Action name: command/unsubscribe
status string Operation execution status (success or error).
requestId object Request unique identifier as specified in the request message.

Device: command/update

Updates an existing device command.

Request Message

Authorization

Device

Message Representation

{
    "action": {string},
    "requestId": {object},
    "deviceId": {string},
    "deviceKey": {string},
    "commandId": {integer},
    "command": {
        "command": {string},
        "parameters": {object},
        "lifetime": {integer},
        "status": {string},
        "result": {object}
    }
}

Message Parameters

Property Name Required Type Description
action Yes string Action name: command/update
requestId No object Request unique identifier, will be passed back in the response message.
deviceId No string Device unique identifier (specify if not authenticated).
deviceKey No string Device authentication key (specify if not authenticated).
commandId Yes integer Device command identifier.
command Yes object A DeviceCommand resource to update.
command.command No string Command name.
command.parameters No object Command parameters, a JSON object with an arbitrary structure.
command.lifetime No integer Command lifetime, a number of seconds until this command expires.
command.status No string Command status, as reported by device or related infrastructure.
command.result No object Command execution result, an optional value that could be provided by device.

Server Message

Message Representation

{
    "action": {string},
    "status": {string},
    "requestId": {object}
}

Message Parameters

Property Name Type Description
action string Action name: command/update
status string Operation execution status (success or error).
requestId object Request unique identifier as specified in the request message.

Device: device/get

Gets information about the current device.

Request Message

Authorization

Device

Message Representation

{
    "action": {string},
    "requestId": {object},
    "deviceId": {string},
    "deviceKey": {string}
}

Message Parameters

Property Name Required Type Description
action Yes string Action name: device/get
requestId No object Request unique identifier, will be passed back in the response message.
deviceId No string Device unique identifier (specify if not authenticated).
deviceKey No string Device authentication key (specify if not authenticated).

Server Message

Message Representation

{
    "action": {string},
    "status": {string},
    "requestId": {object},
    "device": {
        "id": {string},
        "name": {string},
        "status": {string},
        "data": {object},
        "network": {
            "id": {integer},
            "name": {string},
            "description": {string}
        },
        "deviceClass": {
            "id": {integer},
            "name": {string},
            "version": {string},
            "isPermanent": {boolean},
            "offlineTimeout": {integer},
            "data": {object},
            "equipment": [
                {
                    "id": {integer},
                    "name": {string},
                    "code": {string},
                    "type": {string},
                    "data": {object}
                }
            ]
        }
    }
}

Message Parameters

Property Name Type Description
action string Action name: device/get
status string Operation execution status (success or error).
requestId object Request unique identifier as specified in the request message.
device object The Device resource representing the current device.
device.id string Device unique identifier.
device.name string Device display name.
device.status string Device operation status. The status is optional and it can be set to an arbitrary value, if applicable.

If device status monitoring feature is enabled, the framework will set status value to 'Offline' after defined period of inactivity.

device.data object Device data, a JSON object with an arbitrary structure.
device.network object Associated network object.
device.network.id integer Network identifier.
device.network.name string Network display name.
device.network.description string Network description.
device.deviceClass object Associated device class object.
device.deviceClass.id integer Device class identifier.
device.deviceClass.name string Device class display name.
device.deviceClass.version string Device class version.
device.deviceClass.isPermanent boolean Indicates whether device class is permanent. Permanent device classes could not be modified by devices during registration.
device.deviceClass.offlineTimeout integer If set, specifies inactivity timeout in seconds before the framework changes device status to 'Offline'. Device considered inactive when it's not persistently connected and does not send any notifications.
device.deviceClass.data object Device class data, a JSON object with an arbitrary structure.
device.deviceClass.equipment array A collection of associated equipment objects.
device.deviceClass.equipment[].id integer Equipment identifier.
device.deviceClass.equipment[].name string Equipment display name.
device.deviceClass.equipment[].code string Equipment code. It's used to reference particular equipment and it should be unique within a device class.
device.deviceClass.equipment[].type string Equipment type. An arbitrary string representing equipment capabilities.
device.deviceClass.equipment[].data object Equipment data, a JSON object with an arbitrary structure.

Device: device/save

Registers or updates a device.

Request Message

Authorization

Device

Message Representation

{
    "action": {string},
    "requestId": {object},
    "deviceId": {string},
    "deviceKey": {string},
    "deviceKey": {string},
    "deviceId": {string},
    "device": {
        "key": {string},
        "name": {string},
        "status": {string},
        "data": {object},
        "network": {
            "name": {string},
            "description": {string}
        },
        "deviceClass": {
            "name": {string},
            "version": {string},
            "isPermanent": {boolean},
            "offlineTimeout": {integer},
            "data": {object},
            "equipment": [
                {
                    "name": {string},
                    "code": {string},
                    "type": {string},
                    "data": {object}
                }
            ]
        }
    }
}

Message Parameters

Property Name Required Type Description
action Yes string Action name: device/save
requestId No object Request unique identifier, will be passed back in the response message.
deviceId No string Device unique identifier (specify if not authenticated).
deviceKey Yes string Device authentication key.
deviceKey No string Device authentication key (specify if not authenticated).
deviceId Yes string Device unique identifier.
device Yes object A Device resource to register or update.
device.key No string Device authentication key. The key is set during device registration and it has to be provided for all subsequent calls initiated by device. The key maximum length is 64 characters.
device.name Yes string Device display name.
device.status No string Device operation status. The status is optional and it can be set to an arbitrary value, if applicable.

If device status monitoring feature is enabled, the framework will set status value to 'Offline' after defined period of inactivity.

device.data No object Device data, a JSON object with an arbitrary structure.
device.network No object

A Network object which includes name property to match.

In case when the target network is protected with a key, the key value must also be included.

For test deployments, any non-existing networks are automatically created.

device.network.name Yes string Network display name.
device.network.description No string Network description.
device.deviceClass Yes object

A DeviceClass object which includes name and version properties to match.

The device class objects are automatically created/updated unless the DeviceClass.IsPermanent flag is set.

device.deviceClass.name Yes string Device class display name.
device.deviceClass.version Yes string Device class version.
device.deviceClass.isPermanent No boolean Indicates whether device class is permanent. Permanent device classes could not be modified by devices during registration.
device.deviceClass.offlineTimeout No integer If set, specifies inactivity timeout in seconds before the framework changes device status to 'Offline'. Device considered inactive when it's not persistently connected and does not send any notifications.
device.deviceClass.data No object Device class data, a JSON object with an arbitrary structure.
device.deviceClass.equipment No array A collection of associated equipment objects.
device.deviceClass.equipment[].name Yes string Equipment display name.
device.deviceClass.equipment[].code Yes string Equipment code. It's used to reference particular equipment and it should be unique within a device class.
device.deviceClass.equipment[].type Yes string Equipment type. An arbitrary string representing equipment capabilities.
device.deviceClass.equipment[].data No object Equipment data, a JSON object with an arbitrary structure.

Server Message

Message Representation

{
    "action": {string},
    "status": {string},
    "requestId": {object}
}

Message Parameters

Property Name Type Description
action string Action name: device/save
status string Operation execution status (success or error).
requestId object Request unique identifier as specified in the request message.

Device: notification/insert

Creates new device notification.

Request Message

Authorization

Device

Message Representation

{
    "action": {string},
    "requestId": {object},
    "deviceId": {string},
    "deviceKey": {string},
    "notification": {
        "notification": {string},
        "parameters": {object}
    }
}

Message Parameters

Property Name Required Type Description
action Yes string Action name: notification/insert
requestId No object Request unique identifier, will be passed back in the response message.
deviceId No string Device unique identifier (specify if not authenticated).
deviceKey No string Device authentication key (specify if not authenticated).
notification Yes object A DeviceNotification resource to create.
notification.notification Yes string Notification name.
notification.parameters No object Notification parameters, a JSON object with an arbitrary structure.

Server Message

Message Representation

{
    "action": {string},
    "status": {string},
    "requestId": {object},
    "notification": {
        "id": {integer},
        "timestamp": {datetime}
    }
}

Message Parameters

Property Name Type Description
action string Action name: notification/insert
status string Operation execution status (success or error).
requestId object Request unique identifier as specified in the request message.
notification object An inserted DeviceNotification resource.
notification.id integer Notification identifier.
notification.timestamp datetime Notification timestamp (UTC).

Device: server/info

Gets meta-information of the current API.

Request Message

Authorization

None

Message Representation

{
    "action": {string},
    "requestId": {object}
}

Message Parameters

Property Name Required Type Description
action Yes string Action name: server/info
requestId No object Request unique identifier, will be passed back in the response message.

Server Message

Message Representation

{
    "action": {string},
    "status": {string},
    "requestId": {object},
    "info": {
        "apiVersion": {string},
        "serverTimestamp": {datetime},
        "restServerUrl": {string}
    }
}

Message Parameters

Property Name Type Description
action string Action name: server/info
status string Operation execution status (success or error).
requestId object Request unique identifier as specified in the request message.
info object The ApiInfo resource.
info.apiVersion string API version.
info.serverTimestamp datetime Current server timestamp.
info.restServerUrl string REST server URL.

Device: srv: command/insert

Notifies the device about new command.

Server Message

Message Representation

{
    "action": {string},
    "deviceGuid": {string},
    "command": {
        "id": {integer},
        "timestamp": {datetime},
        "userId": {integer},
        "command": {string},
        "parameters": {object},
        "lifetime": {integer},
        "status": {string},
        "result": {object}
    }
}

Message Parameters

Property Name Type Description
action string Action name: command/insert
deviceGuid string Device unique identifier.
command object A DeviceCommand resource representing the command.
command.id integer Command identifier.
command.timestamp datetime Command timestamp (UTC).
command.userId integer Associated user identifier.
command.command string Command name.
command.parameters object Command parameters, a JSON object with an arbitrary structure.
command.lifetime integer Command lifetime, a number of seconds until this command expires.
command.status string Command status, as reported by device or related infrastructure.
command.result object Command execution result, an optional value that could be provided by device.