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

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
200 Success 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

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 Max command entries to return (ordered by time descending) 1 limit=10
since N Look for command entries since this time (ms since epoch) since=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/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

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 Max log entries to return (ordered by time descending) 1 limit=10
since N Look for log entries since this time (ms since epoch) since=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/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 Max state entries to return (ordered by time descending) 1 limit=10
since N Look for state entries since this time (ms since epoch) since=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/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 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

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
200 Success 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 Single or Multiple Device 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