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.

Attribute Names

Gets the attribute names that match the given query. Maximum 1K returned.

Method And Url

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

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.attributeNames.

Request Path Components

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

Request Query Parameters

Name Required Description Default Example
query N Device filter JSON object. See Advanced Device Query for more details. query={”$or”:[{”name”:{”$ne”:”myValue”}},{”parentId”:”575ec8687ae143cd83dc4a97”}]}
dataType N Filter the devices by the given attribute data type or types. See Device Attribute Data Type Filter for more details. dataType[0]=number&dataType[1]=blob
startsWith N Filter attributes down to those that have names starting with the given string. Case insensitive. startsWith=temper

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

Successful Responses

Code Type Description
200 Attribute Names Response The matching attribute names

Error Responses

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

Delete

Delete devices

Method And Url

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

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.delete.

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

{
  "query": {
    "name": {
      "$ne": "My Device"
    }
  },
  "email": "email@example.com"
}

Curl Example 

curl -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN' \
    -X POST \
    -d '{"query":{"name":{"$ne":"My Device"}},"email":"email@example.com"}' \
    https://api.losant.com/applications/APPLICATION_ID/devices/delete

Successful Responses

Code Type Description
200 Bulk Deletion Response Object indicating number of devices deleted or failed
202 Job Enqueued API Result If a job was enqueued for the devices to be deleted

Error Responses

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

Device Names

Gets the device names that match the given query. Maximum 1K returned.

Method And Url

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

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.deviceNames.

Request Path Components

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

Request Query Parameters

Name Required Description Default Example
query N Device filter JSON object. See Advanced Device Query for more details. query={”$or”:[{”name”:{”$ne”:”myValue”}},{”parentId”:”575ec8687ae143cd83dc4a97”}]}
startsWith N Filter devices down to those that have names starting with the given string. Case insensitive. startsWith=temper

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

Successful Responses

Code Type Description
200 Device Names Response The matching device names

Error Responses

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

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

Request Body

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

{
  "query": {
    "name": {
      "$ne": "My Device"
    }
  },
  "email": "email@example.com"
}

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
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 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, connectionStatus, deletedAt 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 100 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 or classes. See Device Class Filter for more details. deviceClass[0]=standalone&deviceClass[1]=edgeCompute
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
parentId N Filter devices as children of a given system id parentId=575ecf887ae143cd83dc4aa2
query N Device filter JSON object which overrides the filterField, filter, deviceClass, tagFilter, and parentId parameters. See Advanced Device Query for more details. query={”$or”:[{”name”:{”$ne”:”myValue”}},{”parentId”:”575ec8687ae143cd83dc4a97”}]}
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
queryDeleted N If true, endpoint will return recently deleted devices instead queryDeleted=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

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

Get Composite State

Retrieve the composite last complete state of the matching devices

Method And Url

GET https://api.losant.com/applications/APPLICATION_ID/devices/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, devices.*, or devices.getCompositeState.

Request Path Components

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

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
sortField N Field to sort the results by. Accepted values are: name, id, creationDate, lastUpdated, connectionStatus 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 100 perPage=10
query N Device advanced query JSON object. See Advanced Device Query for more details. query={”$or”:[{”name”:{”$ne”:”myValue”}},{”parentId”:”575ec8687ae143cd83dc4a97”}]}

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

Successful Responses

Code Type Description
200 Devices Composite State Collection of composite last state of the devices

Error Responses

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

Patch

Update the fields of one or more devices

Method And Url

PATCH 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.patch.

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

{
  "updateFields": {
    "name": "My Updated Device",
    "description": "Description of my updated device",
    "tags": [
      {
        "key": "TagKey",
        "value": "TagValue"
      }
    ],
    "attributes": [
      {
        "name": "voltage",
        "dataType": "number"
      }
    ],
    "deviceClass": "standalone"
  },
  "deviceIds": [
    "575ecec57ae143cd83dc4a9f",
    "575ecec57ae143cd83dc4a9e",
    "575ecec57ae143cd83dc4a9a"
  ]
}

Curl Example 

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

Successful Responses

Code Type Description
200 Devices Updated Object including an update log link and the number of devices updated, failed, and skipped
202 Job Enqueued API Result Successfully queued bulk update job

Error Responses

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

Payload Counts

Creates an export of payload count information for the matching devices

Method And Url

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

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

{
  "query": {
    "name": {
      "$ne": "My Device"
    }
  },
  "email": "email@example.com"
}

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

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

Remove Data

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

Method And Url

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

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.removeData.

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

{
  "query": {
    "name": {
      "$ne": "My Device"
    }
  },
  "start": 1,
  "end": 0,
  "attributes": [
    "deleteMyData",
    "mineToo"
  ]
}

Curl Example 

curl -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN' \
    -X POST \
    -d '{"query":{"name":{"$ne":"My Device"}},"start":1,"end":0,"attributes":["deleteMyData","mineToo"]}' \
    https://api.losant.com/applications/APPLICATION_ID/devices/removeData

Successful Responses

Code Type Description
202 Job Enqueued API Result If a job was enqueued for device data to be removed

Error Responses

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

Restore

Restore deleted devices

Method And Url

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

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.restore.

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

{
  "query": {
    "name": {
      "$ne": "My Device"
    }
  },
  "email": "email@example.com"
}

Curl Example 

curl -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN' \
    -X POST \
    -d '{"query":{"name":{"$ne":"My Device"}},"email":"email@example.com"}' \
    https://api.losant.com/applications/APPLICATION_ID/devices/restore

Successful Responses

Code Type Description
200 Bulk Restoration Response Object indicating number of devices restored or failed
202 Job Enqueued API Result If a job was enqueued for the devices to be restored

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
202 Job Enqueued API Result If command was queued to be sent

Error Responses

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

Tag Keys

Gets the unique tag keys for devices that match the given query. Maximum 1K returned.

Method And Url

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

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.tagKeys.

Request Path Components

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

Request Query Parameters

Name Required Description Default Example
query N Device filter JSON object. See Advanced Device Query for more details. query={”$or”:[{”name”:{”$ne”:”myValue”}},{”parentId”:”575ec8687ae143cd83dc4a97”}]}
startsWith N Filter keys down to those that start with the given string. Case insensitive. startsWith=temper

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

Successful Responses

Code Type Description
200 Tag Keys Response The matching tag keys

Error Responses

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

Tag Values

Gets the unique tag values for the given key for devices that match the given query. Maximum 1K returned.

Method And Url

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

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.tagValues.

Request Path Components

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

Request Query Parameters

Name Required Description Default Example
query N Device filter JSON object. See Advanced Device Query for more details. query={”$or”:[{”name”:{”$ne”:”myValue”}},{”parentId”:”575ec8687ae143cd83dc4a97”}]}
key Y The tag key to get the values for key=myKey
startsWith N Filter values down to those that start with the given string. Case insensitive. startsWith=temper

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/tagValues?key=myKey

Successful Responses

Code Type Description
200 Tag Values Response The matching tag values

Error Responses

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

Was this page helpful?

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