Application Actions

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

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

Archive Data

Returns success when a job has been enqueued to archive this application’s device data for a given day

Method And Url

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

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, application.*, or application.archiveData.

Request Path Components

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

Request Query Parameters

Name Required Description Default Example
date Y The date to archive data (ms since epoch), it must be within the archive time range older than 31 days and newer than the organizations dataTTL date=1518556791829

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/archiveData?date=1518556791829

Successful Responses

Code Type Description
200 Success Enqueued a job to archive this applications device data

Error Responses

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

Backfill Archive Data

Returns success when a job has been enqueued to backfill all current data to it’s archive

Method And Url

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

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, application.*, or application.backfillArchiveData.

Request Path Components

Path Component Description Example
APPLICATION_ID ID of the associated application 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/backfillArchiveData

Successful Responses

Code Type Description
200 Success Enqueued a job to backfill device data to this application archive location

Error Responses

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

Delete

Deletes an application

Method And Url

DELETE https://api.losant.com/applications/APPLICATION_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, application.*, or application.delete.

Request Path Components

Path Component Description Example
APPLICATION_ID ID of the associated application 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 DELETE \
    https://api.losant.com/applications/APPLICATION_ID

Successful Responses

Code Type Description
200 Success If application was successfully deleted

Error Responses

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

Get

Retrieves information on an application

Method And Url

GET https://api.losant.com/applications/APPLICATION_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.Organization, all.Organization.read, all.User, all.User.read, application.*, or application.get.

Request Path Components

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

Request Query Parameters

Name Required Description Default Example
summaryExclude N Comma-separated list of summary fields to exclude from application summary summaryExclude=payloadCount
summaryInclude N Comma-separated list of summary fields to include in application summary summaryInclude=payloadCount

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

Successful Responses

Code Type Description
200 Application Application information

Error Responses

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

Mqtt Publish Message

Publishes the given message to the given MQTT topic

Method And Url

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

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, application.*, or application.mqttPublishMessage.

Request Path Components

Path Component Description Example
APPLICATION_ID ID of the associated 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 MQTT Publish Body schema. For example, the following would be a valid body for this request:

{
  "topic": "an/mqtt/topic",
  "message": "The MQTT message!"
}

Curl Example 

curl -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN' \
    -X POST \
    -d '{"topic":"an/mqtt/topic","message":"The MQTT message!"}' \
    https://api.losant.com/applications/APPLICATION_ID/mqttPublishMessage

Successful Responses

Code Type Description
200 Success Message successfully published

Error Responses

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

Mqtt Subscription Stream

Attach to a real time stream of state messages for the given MQTT topic using Server Sent Events (SSE)

Method And Url

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

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, application.*, or application.mqttSubscriptionStream.

Request Path Components

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

Request Query Parameters

Name Required Description Default Example
keepAliveInterval N Number of seconds between keepalive messages 2 keepAliveInterval=2
topic Y The MQTT topic to subscribe to topic=my/topic

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/mqttSubscriptionStream?topic=my%2Ftopic

SSE Stream for a Successful Response

SSE stream of mqtt messages for the requested topic

SSE Event Name Type Description
mqttMessage MQTT Publish Body An SSE event representing a single mqtt payload

Error Responses

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

Patch

Updates information about an application

Method And Url

PATCH https://api.losant.com/applications/APPLICATION_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, application.*, or application.patch.

Request Path Components

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

Request Query Parameters

Name Required Description Default Example
summaryExclude N Comma-separated list of summary fields to exclude from application summary summaryExclude=payloadCount
summaryInclude N Comma-separated list of summary fields to include in application summary summaryInclude=payloadCount

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

{
  "name": "My Updated Application",
  "description": "Description of my updated application"
}

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 Application","description":"Description of my updated application"}' \
    https://api.losant.com/applications/APPLICATION_ID

Successful Responses

Code Type Description
200 Application Updated application information

Error Responses

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

Payload Counts

Returns payload counts for the time range specified for this application

Method And Url

GET https://api.losant.com/applications/APPLICATION_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, application.*, or application.payloadCounts.

Request Path Components

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

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

Successful Responses

Code Type Description
200 Payload Counts Payload counts, by type and source

Error Responses

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

Search across an application’s resources by target identifier

Method And Url

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

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, application.*, or application.search.

Request Path Components

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

Request Query Parameters

Name Required Description Default Example
filter Y The partial resource name being searched for filter=my dev

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/search?filter=my%20dev

Successful Responses

Code Type Description
200 Application Search Result An array of resource ids, names, descriptions, and types matching the search query

Error Responses

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