Device Actions

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

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

Command Stream

Attach to a real time stream of command messages to this device using Server Sent Events (SSE)

Method And Url

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

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, device.*, or device.commandStream.

Request Path Components

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

Request Query Parameters

Name Required Description Default Example
keepAliveInterval N Number of seconds between keepalive messages 2 keepAliveInterval=2

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/DEVICE_ID/commandStream

SSE Stream for a Successful Response

SSE stream of new command messages for this device

SSE Event Name Type Description
deviceCommand Device Command An SSE event representing a single device command

Error Responses

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

Delete

Deletes a device

Method And Url

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

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, device.*, or device.delete.

Request Path Components

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

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 DELETE \
    https://api.losant.com/applications/APPLICATION_ID/devices/DEVICE_ID

Successful Responses

Code Type Description
200 Success If device was successfully deleted

Error Responses

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

Export

Creates a device data export. Defaults to all data.

Method And Url

POST https://api.losant.com/applications/APPLICATION_ID/devices/DEVICE_ID/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, device.*, or device.export.

Request Path Components

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

Request Query Parameters

Name Required Description Default Example
start N Start time of export (ms since epoch - 0 means now, negative is relative to now) 1 start=1465790400000
end N End time of export (ms since epoch - 0 means now, negative is relative to now) 0 end=1465790400000
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
includeBlobData N If set will export any blob attributes in base64 form, otherwise they will be downloadable links which will expire. includeBlobData=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 POST \
    https://api.losant.com/applications/APPLICATION_ID/devices/DEVICE_ID/export

Successful Responses

Code Type Description
202 Job Enqueued API Result If generation of export was successfully started

Error Responses

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

Get

Retrieves information on a device

Method And Url

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

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, device.*, or device.get.

Request Path Components

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

Request Query Parameters

Name Required Description Default Example
excludeConnectionInfo N If set, do not return connection info excludeConnectionInfo=true
tagsAsObject N Return tags as an object map instead of an array tagsAsObject=true
attributesAsObject N Return attributes as an object map instead of an array attributesAsObject=false

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/DEVICE_ID

Successful Responses

Code Type Description
200 Device Device information

Error Responses

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

Get Command

Retrieve the last known commands(s) sent to the device

Method And Url

GET https://api.losant.com/applications/APPLICATION_ID/devices/DEVICE_ID/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.Application.read, all.Device, all.Device.read, all.Organization, all.Organization.read, all.User, all.User.read, device.*, or device.getCommand.

Request Path Components

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

Request Query Parameters

Name Required Description Default Example
limit N Maximum number of command entries to return 1 limit=10
since N (deprecated) Look for command entries since this time (ms since epoch) since=1465790400000
sortDirection N Direction to sort the command entries (by time). Accepted values are: asc, desc desc sortDirection=desc
duration N Duration of time range to query in milliseconds duration=86400000
start N Start of time range to query in milliseconds since epoch start=1465790400000
end N End of time range to query in milliseconds since epoch end=0

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/DEVICE_ID/command

Successful Responses

Code Type Description
200 Device Commands Recent device commands

Error Responses

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

Get Composite State

Retrieve the composite last complete state of the device

Method And Url

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

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, device.*, or device.getCompositeState.

Request Path Components

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

Request Query Parameters

Name Required Description Default Example
start N Start of time range to look at to build composite state 1 start=1465790400000
end N End of time range to look at to build composite state 0 end=1465790400000
attributes N Comma-separated list of attributes to include. When not provided, returns all attributes. attributes=myAttr1,myAttr2

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/DEVICE_ID/compositeState

Successful Responses

Code Type Description
200 Composite Device State Composite last state of the device

Error Responses

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

Get Log Entries

Retrieve the recent log entries about the device

Method And Url

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

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, device.*, or device.getLogEntries.

Request Path Components

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

Request Query Parameters

Name Required Description Default Example
limit N Maximum number of log entries to return 1 limit=10
since N (deprecated) Look for log entries since this time (ms since epoch) since=1465790400000
sortDirection N Direction to sort the log entries (by time). Accepted values are: asc, desc desc sortDirection=desc
duration N Duration of time range to query in milliseconds duration=86400000
start N Start of time range to query in milliseconds since epoch start=1465790400000
end N End of time range to query in milliseconds since epoch end=0

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/DEVICE_ID/logs

Successful Responses

Code Type Description
200 Device Log Recent log entries

Error Responses

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

Get State

Retrieve the last known state(s) of the device

Method And Url

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

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, device.*, or device.getState.

Request Path Components

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

Request Query Parameters

Name Required Description Default Example
limit N Maximum number of state entries to return 1 limit=10
since N (deprecated) Look for state entries since this time (ms since epoch) since=1465790400000
sortDirection N Direction to sort the state entries (by time). Accepted values are: asc, desc desc sortDirection=desc
duration N Duration of time range to query in milliseconds duration=86400000
start N Start of time range to query in milliseconds since epoch start=1465790400000
end N End of time range to query in milliseconds since epoch end=0

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/DEVICE_ID/state

Successful Responses

Code Type Description
200 Device States Recent device states

Error Responses

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

Patch

Updates information about a device

Method And Url

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

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, device.*, or device.patch.

Request Path Components

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

Request Query Parameters

Name Required Description Default Example
tagsAsObject N Return tags as an object map instead of an array tagsAsObject=true
attributesAsObject N Return attributes as an object map instead of an array attributesAsObject=false

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 Patch schema. For example, the following would be a valid body for this request:

{
  "name": "My Updated Device",
  "description": "Description of my updated 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 PATCH \
    -d '{"name":"My Updated Device","description":"Description of my updated device","tags":[{"key":"TagKey","value":"TagValue"}],"attributes":[{"name":"voltage","dataType":"number"}],"deviceClass":"standalone"}' \
    https://api.losant.com/applications/APPLICATION_ID/devices/DEVICE_ID

Successful Responses

Code Type Description
200 Device Updated device information

Error Responses

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

Payload Counts

Returns payload counts for the time range specified for this device

Method And Url

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

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, device.*, or device.payloadCounts.

Request Path Components

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

Request Query Parameters

Name Required Description Default Example
start N Start of range for payload count query (ms since epoch) -2592000000 start=0
end N End of range for payload count query (ms since epoch) 0 end=1465790400000

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/DEVICE_ID/payloadCounts

Successful Responses

Code Type Description
200 Device Payload Counts Payload counts, by type

Error Responses

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

Payload Counts Breakdown

Returns payload counts per resolution in the time range specified for this device

Method And Url

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

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, device.*, or device.payloadCountsBreakdown.

Request Path Components

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

Request Query Parameters

Name Required Description Default Example
start N Start of range for payload count query (ms since epoch) -2592000000 start=0
end N End of range for payload count query (ms since epoch) 0 end=1465790400000
resolution N Resolution in milliseconds. Accepted values are: 86400000, 3600000 86400000 resolution=86400000

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/DEVICE_ID/payloadCountsBreakdown

Successful Responses

Code Type Description
200 Payload Counts Breakdown Sum of payload counts by date

Error Responses

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

Remove Data

Removes all device data for the specified time range. Defaults to all data.

Method And Url

DELETE https://api.losant.com/applications/APPLICATION_ID/devices/DEVICE_ID/data

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, device.*, or device.removeData.

Request Path Components

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

Request Query Parameters

Name Required Description Default Example
start N Start time of export (ms since epoch - 0 means now, negative is relative to now) 1 start=1465790400000
end N End time of export (ms since epoch - 0 means now, negative is relative to now) 0 end=1465790400000

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 DELETE \
    https://api.losant.com/applications/APPLICATION_ID/devices/DEVICE_ID/data

Successful Responses

Code Type Description
202 Job Enqueued API Result If data removal was successfully started

Error Responses

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

Send Command

Send a command to a device

Method And Url

POST https://api.losant.com/applications/APPLICATION_ID/devices/DEVICE_ID/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, device.*, or device.sendCommand.

Request Path Components

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

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 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
  ]
}

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]}' \
    https://api.losant.com/applications/APPLICATION_ID/devices/DEVICE_ID/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 device was not found

Send State

Send the current state of the device

Method And Url

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

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, device.*, or device.sendState.

Request Path Components

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

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 State or States schema. For example, the following would be a valid body for this request:

{
  "time": "2016-06-13T04:00:00.000Z",
  "data": {
    "voltage": 22.4
  }
}

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","data":{"voltage":22.4}}' \
    https://api.losant.com/applications/APPLICATION_ID/devices/DEVICE_ID/state

Successful Responses

Code Type Description
200 Success If state was successfully received

Error Responses

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

Set Connection Status

Set the current connection status of the device

Method And Url

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

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, device.*, or device.setConnectionStatus.

Request Path Components

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

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 Connection Status schema. For example, the following would be a valid body for this request:

{
  "status": "connected"
}

Curl Example 

curl -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN' \
    -X POST \
    -d '{"status":"connected"}' \
    https://api.losant.com/applications/APPLICATION_ID/devices/DEVICE_ID/setConnectionStatus

Successful Responses

Code Type Description
200 Success If connection status was successfully applied

Error Responses

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

State Stream

Attach to a real time stream of state messages from this device using Server Sent Events (SSE)

Method And Url

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

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, device.*, or device.stateStream.

Request Path Components

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

Request Query Parameters

Name Required Description Default Example
keepAliveInterval N Number of seconds between keepalive messages 2 keepAliveInterval=2

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/DEVICE_ID/stateStream

SSE Stream for a Successful Response

SSE stream of new state messages for this device

SSE Event Name Type Description
deviceState Device State An SSE event representing a single device state

Error Responses

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

Was this page helpful?

Still looking for help? You can also search the Losant Forums or submit your question there.