Devices Actions#

https://api.losant.com/applications/APPLICATION_ID/devices

Below are the various requests that can be performed against the Devices resource, as well as the expected parameters and the potential responses.

Export#

Creates an export of all device metadata.

Method And Url #

POST https://api.losant.com/applications/APPLICATION_ID/devices/export

Authentication #

A valid api access token is required to access this endpoint. The token must include at least one of the following scopes: all.Application, all.Application.read, all.Organization, all.Organization.read, all.User, all.User.read, devices.*, or devices.export.

Request Path Components #

Path Component Description Example
APPLICATION_ID ID associated with the application 575ec8687ae143cd83dc4a97

Request Query Parameters #

Name Required Description Default Example
email N Email address to send export to. Defaults to current user's email. email=email@example.com
callbackUrl N Callback URL to call with export result. callbackUrl=https://example.com/cburl

Request Headers #

Name Required Description Default
Authorization Y The token for authenticating the request, prepended with Bearer

Curl Example #

curl -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN' \
    -X POST \
    https://api.losant.com/applications/APPLICATION_ID/devices/export

Successful Responses #

Code Type Description
200 Success If generation of export was successfully started

Error Responses #

Code Type Description
400 Error Error if malformed request
404 Error Error if application was not found

Get#

Returns the devices for an application

Method And Url #

GET https://api.losant.com/applications/APPLICATION_ID/devices

Authentication #

A valid api access token is required to access this endpoint. The token must include at least one of the following scopes: all.Application, all.Application.read, all.Device, all.Device.read, all.Organization, all.Organization.read, all.User, all.User.read, devices.*, or devices.get.

Request Path Components #

Path Component Description Example
APPLICATION_ID ID associated with the application 575ec8687ae143cd83dc4a97

Request Query Parameters #

Name Required Description Default Example
sortField N Field to sort the results by. Accepted values are: name, id, creationDate, lastUpdated name sortField=name
sortDirection N Direction to sort the results by. Accepted values are: asc, desc asc sortDirection=asc
page N Which page of results to return 0 page=0
perPage N How many items to return per page 1000 perPage=10
filterField N Field to filter the results by. Blank or not provided means no filtering. Accepted values are: name filterField=name
filter N Filter to apply against the filtered field. Supports globbing. Blank or not provided means no filtering. filter=my * device
deviceClass N Filter the devices by the given device class. Accepted values are: standalone, gateway, peripheral, floating, edgeCompute deviceClass=standalone
tagFilter N Array of tag pairs to filter by. See Device Tag Filter for more details. tagFilter[0][key]=Floor&tagFilter[0][value]=2&tagFilter[1][key]=Serial
excludeConnectionInfo N If set, do not return connection info excludeConnectionInfo=true

Request Headers #

Name Required Description Default
Authorization Y The token for authenticating the request, prepended with Bearer

Curl Example #

curl -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN' \
    -X GET \
    https://api.losant.com/applications/APPLICATION_ID/devices

Successful Responses #

Code Type Description
200 Devices Collection of devices

Error Responses #

Code Type Description
400 Error Error if malformed request
404 Error Error if application was not found

Post#

Create a new device for an application

Method And Url #

POST https://api.losant.com/applications/APPLICATION_ID/devices

Authentication #

A valid api access token is required to access this endpoint. The token must include at least one of the following scopes: all.Application, all.Organization, all.User, devices.*, or devices.post.

Request Path Components #

Path Component Description Example
APPLICATION_ID ID associated with the application 575ec8687ae143cd83dc4a97

Request Headers #

Name Required Description Default
Authorization Y The token for authenticating the request, prepended with Bearer

Request Body #

The body of the request should be serialized JSON that validates against the Device Post schema. For example, the following would be a valid body for this request:

{
  "name": "My New Device",
  "description": "Description of my new device",
  "tags": [
    {
      "key": "TagKey",
      "value": "TagValue"
    }
  ],
  "attributes": [
    {
      "name": "voltage",
      "dataType": "number"
    }
  ],
  "deviceClass": "standalone"
}

Curl Example #

curl -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN' \
    -X POST \
    -d '{"name":"My New Device","description":"Description of my new device","tags":[{"key":"TagKey","value":"TagValue"}],"attributes":[{"name":"voltage","dataType":"number"}],"deviceClass":"standalone"}' \
    https://api.losant.com/applications/APPLICATION_ID/devices

Successful Responses #

Code Type Description
201 Device Successfully created device

Error Responses #

Code Type Description
400 Error Error if malformed request
404 Error Error if application was not found

Send Command#

Send a command to multiple devices

Method And Url #

POST https://api.losant.com/applications/APPLICATION_ID/devices/command

Authentication #

A valid api access token is required to access this endpoint. The token must include at least one of the following scopes: all.Application, all.Device, all.Organization, all.User, devices.*, or devices.sendCommand.

Request Path Components #

Path Component Description Example
APPLICATION_ID ID associated with the application 575ec8687ae143cd83dc4a97

Request Headers #

Name Required Description Default
Authorization Y The token for authenticating the request, prepended with Bearer

Request Body #

The body of the request should be serialized JSON that validates against the Multi Device Command schema. For example, the following would be a valid body for this request:

{
  "time": "2016-06-13T04:00:00.000Z",
  "name": "myCommand",
  "payload": [
    1,
    1,
    2,
    3,
    5
  ],
  "deviceTags": [
    {
      "key": "floor",
      "value": 8
    }
  ]
}

Curl Example #

curl -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN' \
    -X POST \
    -d '{"time":"2016-06-13T04:00:00.000Z","name":"myCommand","payload":[1,1,2,3,5],"deviceTags":[{"key":"floor","value":8}]}' \
    https://api.losant.com/applications/APPLICATION_ID/devices/command

Successful Responses #

Code Type Description
200 Success If command was successfully sent

Error Responses #

Code Type Description
400 Error Error if malformed request
404 Error Error if application was not found