Losant REST API
Losant is powered by a full REST API that provides access to nearly every feature. The Losant front-end web application itself is built on top of this API, and so almost all the data and functionality in the front end is available through the API itself. In fact, the front-end uses the open-source losant-rest-js JavaScript client to communicate with the Losant API. If JavaScript is not your language of choice, no need to worry! We have easy to use libraries for a number of different languages:
- JavaScript with losant-rest-js - Available in Node Package Manager (
npm install losant-rest
) - Python with losant-rest-python - Available in the Python Package Index (
pip install losant-rest
) - Ruby with losant-rest-ruby - Available in RubyGems (
gem install losant_rest
)
Of course, if you are working in a language not listed above, the API is reasonably easy to use directly - if your language has a good HTTP request library and a good JSON library, you should be able to make any API request you need using the documentation here.
All of the documentation and examples here are aimed at making direct HTTP requests against the Losant API, using curl examples whenever possible. If you plan on using one of the wrapping libraries listed above, the documentation in those repositories will be a much more useful place to learn how to use the particular library.
Content & Encoding
The Losant API uses JSON for almost all requests and responses - all request bodies should be JSON encoded, and all responses will be encoded JSON, even in the case of errors. So every request should have both the Content-Type
and Accept
headers set to application/json
.
Authenticating a Request
Most endpoints on the Losant API require an API access token. This is done by passing a Bearer Authorization token in the Authorization
header field for the request (e.g. "Authorization": "Bearer your-api-token-goes-here"
).
Obtaining an API Access Token
You can obtain an Authorization Token to use to make authenticated requests by calling one of the Auth endpoints. There are two main endpoints, one for authenticating as a user, and one for authenticating as a device. The JSON response for either endpoint has a token
field, which is the authorization token you should use in the Authorization header in subsequent requests that you want to perform as that user or device.
You can also obtain API access tokens through the Application API Tokens and Application API Token resources. These resources allow you to create and manage API
access tokens specific to a particular application. By default, tokens created for an application will have the scope all.Application
(and will therefore have access to any endpoints that accept the scope all.Application
), but can be created with very specific scopes if desired. An application API token will only ever be able to access and manage resources within the application they were created in.
User-Based Authentication
When authenticated as a user, any API calls have full access to the Losant system. The returned API access token has the scope all.User
, which allows access to any API endpoint. Any applications or dashboards owned by that user can be accessed or modified, and any applications or dashboards that are owned by an organization that the user user is a part of can be accessed (and potentially modified depending on the user's permissions within that organization). Essentially, when authenticated as a user through the API, anything that the user is allowed to do in the normal Losant web interface can be done through the API.
The following shows a sequence of cURL commands for authenticating as a user and using the resulting token to get a list of devices for an application:
curl -H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-X POST \
-d '{ "email": "example@losant.com", "password": "your_password" }' \
https://api.losant.com/auth/user
# Example user authentication result
# {
# "token": "a user auth token string",
# "userId": "theUserId"
# }
curl -H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer a user auth token string' \
-X GET \
https://api.losant.com/applications/anAppId/devices
# Example device listing result
# {
# "count": 1,
# "items": [ {
# "deviceClass": "standalone",
# "connectionInfo": { "connected": 0, "time": "2016-06-01T17:16:02.324Z" },
# "name": "Ruby Client Testing",
# "creationDate": "2016-01-31T17:58:57.541Z",
# "lastUpdated": "2016-05-31T14:47:32.288Z",
# "id": "myDevId",
# "attributes": [
# { "name": "string", "dataType": "string" },
# { "name": "number", "dataType": "number" },
# { "name": "boolean", "dataType": "boolean" }
# ],
# "description": "",
# "_etag": "\"174-u7/3je4oFyaKGePPbcHLqw\"",
# "deviceId": "myDevId",
# "tags": [],
# "applicationId": "myAppId",
# "_type": "device",
# "_links": {
# "application": { "href": "/applications/myAppId" },
# "devices": { "href": "/applications/myAppId/devices" },
# "self": { "href": "/applications/myAppId/devices/myDevId" }
# }
# } ],
# "applicationId": "myAppId",
# "perPage": 100,
# "page": 0,
# "sortField": "name",
# "sortDirection": "asc",
# "totalCount": 1,
# "_type": "devices",
# "_links": {
# "application": { "href": "/applications/myAppId" },
# "self": { "href": "/applications/myAppId/devices" }
# }
# }
Device-Based Authentication
Unlike authenticating as a user, a device authenticated against the API receives a very limited set of permissions. An authenticated device receives an API access token with the scope all.Device
, and so can access any endpoints that accept the authentication scope all.Device
. For example, an authenticated device can read information about itself (Device Get, Devices Get),
send state information about itself to Losant (Device Send State), query historical state information for itself (Device Get State, Data), and query historical commands that were sent to it (Device Get Commands). If the device is a gateway device, it will also be allowed to send state to Losant on behalf of any of its peripheral devices.
If the application access key used to authenticate the device allows more than just the one device, though, the API permissions also expand. The device will have permission to query data about the other devices allowed with that key (general info, historical state, and historical commands). It will also have permission to send commands to those other devices (Device Send Command, Devices Send Command). If the access key used is set to allow "All Devices", a device authenticated with that key will have these read and command permissions for all devices in the application. A device never has access to anything outside of the application it is a member of.
The following shows a sequence of cURL commands for authenticating as a device and using the resulting token to publish state as that device:
curl -H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-X POST \
-d '{ "deviceId": "myDeviceId", "key": "my_app_access_key", "secret": "my_app_access_secret"}' \
https://api.losant.com/auth/device
# Example device authentication result
# {
# "applicationId": "myAppId",
# "token": "a device auth token string",
# "restricted": false,
# "deviceId": "myDeviceId",
# "deviceClass": "standalone"
# }
curl -H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer a device auth token string' \
-X POST \
-d '{ "data": { "temperature": 68.2 } }' \
https://api.losant.com/applications/myAppId/devices/myDeviceId/state
# Example device state push result
# { "success": true }
Resources
Losant's API is organized around individual "resources" wrapping up functionality for a particular item or collection. See each resource documentation page for the particular actions that can be performed on that resource.
Throttles And Limits
The following API endpoints have specific throttling:
- Application: Archive Data is limited to one concurrent call per application.
- Application: Backfill Archive Data is limited to one concurrent call per application.
- Application: Clone is limited to one concurrent import or clone per owner i.e. your sandbox or organization.
- Application: Export is limited to one concurrent export per application.
- Application: Full Data Tables Archive is limited to one concurrent call per application.
- Application: Full Events Archive is limited to one concurrent call per application.
- Applications: Import is limited to one concurrent import or clone per owner i.e. your sandbox or organization.
- Application: Import is limited to one concurrent import per application.
- Application: MQTT Publish Message is limited to 30 calls in a 15-second window per device - or on average, 2 calls per second. This matches the limiting that occurs when sending messages over MQTT.
- Dashboard: Send Report is limited to one concurrent call per dashboard.
- Data: Bulk Export by Query is limited to one concurrent call per application.
- Data: Time Series Query can return a maximum of 30MB of data per request.
- Data Table: Data Export is limited to one concurrent call per data table.
- Data Table Rows: Get and Data Table Rows: Query can return a maximum of 20MB of data per request.
- Device: Data Export is limited to one concurrent call per device.
- Device: Send State is limited to 30 calls in a 15-second window per device - or on average, 2 calls per second. This matches the limiting that occurs when sending messages over MQTT.
- Device: Send Command uses the same throttle as applied to
Device Send State
above, which is limited to 30 calls in a 15-second window (per device) - on average, 2 calls per second. - Device: Set Connection Status uses the same throttle as applied to
Device Send State
above, which is limited to 30 calls in a 15-second window (per device) - on average, 2 calls per second. - Devices: Export is limited to one concurrent call per application.
- Devices: Payload Counts is limited to one concurrent call per application.
- Embedded Deployment: Export is limited to 1 call per 5 minutes per application.
- Event: Create is limited to 15 calls in a 15-second window (per application) - on average, 1 creation per second. This matches the limiting that occurs when creating events through a workflow.
- Event: Export is limited to one concurrent call per application.
- File: Upload multipart/form-data bodies are limited to 10MB. To upload files larger than this (up to 5GB), use the Files: Post or File: Patch endpoint and upload the file directly to the storage provider using the signed URL and credentials returned in response.
- Instance: Generate Report is limited to one concurrent call per instance.
- Notebook: Input Data Export is limited to 1 call per 15 minutes per notebook.
- Workflow: Press Virtual Button is limited to 100 calls in a 10-second window (or, on average, 10 per second) per virtual button.
Was this page helpful?
Still looking for help? You can also search the Losant Forums or submit your question there.