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.

Apply Template

Add resources to an application via an application template

Method And Url

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

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

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

{
  "templateId": "575ec8687ae143cd83dc4a97",
  "email": "email.example.com"
}

Curl Example 

curl -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN' \
    -X PATCH \
    -d '{"templateId":"575ec8687ae143cd83dc4a97","email":"email.example.com"}' \
    https://api.losant.com/applications/APPLICATION_ID/applyTemplate

Successful Responses

Code Type Description
200 Application Updated application information
202 Job Enqueued API Result If a job was enqueued for the resources to be imported into the application

Error Responses

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

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

Clone

Copy an application into a new application

Method And Url

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

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

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

{
  "options": {
    "includeFiles": true,
    "includeDevices": true,
    "ownerType": "organization",
    "ownerId": "575ec8687ae143cd83dc4a98"
  }
}

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

Successful Responses

Code Type Description
200 Success Dry Run if dryRun is set and successful, then return success
201 Application Creation By Template Result If application was successfully cloned
202 Job Enqueued API Result If application was enqueued to be cloned

Error Responses

Code Type Description
400 Error Error if malformed request
404 Error Error if application is not found
422 Validation Error Error if too many validation errors occurred on other resources

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

Export

Export an application and all of its resources

Method And Url

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

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

{
  "includeFiles": true,
  "includeDevices": true,
  "email": "test@losant.com"
}

Curl Example 

curl -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN' \
    -X POST \
    -d '{"includeFiles":true,"includeDevices":true,"email":"test@losant.com"}' \
    https://api.losant.com/applications/APPLICATION_ID/export

Successful Responses

Code Type Description
200 Application Export Result a url to download the zip of exported resources
202 Job Enqueued API Result If application was enqueued to be exported

Error Responses

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

Full Data Tables Archive

Returns success when a job has been enqueued to archive all selected data tables

Method And Url

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

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

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

Successful Responses

Code Type Description
200 Success Enqueued a job to archive all selected data tables of this application archive location

Error Responses

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

Full Events Archive

Returns success when a job has been enqueued to archive all current events

Method And Url

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

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

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

Successful Responses

Code Type Description
200 Success Enqueued a job to archive all events to this application archive location

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

Import

Add multiple resources to an application via a zip file

Method And Url

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

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

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 a multipart form data post containing the following:

Name Required Description Default Example
importBundle Y The zip file containing all of the resources to import into the application
email N Email address to notify the user when the job to import the application resources has completed or errored, defaults to the email address of the user making the request email=email@example.com

Curl Example 

curl -H 'Content-Type: multipart/form-data' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN' \
    -X POST \
    -F importBundle=@localfilename' \
    https://api.losant.com/applications/APPLICATION_ID/import

Successful Responses

Code Type Description
200 Application Updated application information
202 Job Enqueued API Result If a job was enqueued for the resources to be imported into the application

Error Responses

Code Type Description
400 Error Error if malformed request
404 Error Error if application is 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 application 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

Readme

Get the current application readme information

Method And Url

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

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

Successful Responses

Code Type Description
200 Application Readme The application readme information

Error Responses

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

Readme Patch

Update the current application readme information

Method And Url

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

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

{
  "content": "The new readme content"
}

Curl Example 

curl -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN' \
    -X PATCH \
    -d '{"content":"The new readme content"}' \
    https://api.losant.com/applications/APPLICATION_ID/readme

Successful Responses

Code Type Description
200 Application Readme Updated readme information

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