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
deviceState 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