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

Each of the following is a resource on the Losant API, 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.

  • Application
    Contains all of the actions that can be performed against a single Application, which include things like getting info on an application or modifying an application.

  • Applications
    Contains all of the actions that can be performed against the set of Applications that the currently authenticated user has access to - such as listing the applications or creating a new application.

  • Application API Token
    Contains all the actions that can be performed against a single API Access Token belonging to an application - for instance, getting info on a single token or revoking a token.

  • Application API Tokens
    Contains all of the actions that can be performed against the collection of API Access Tokens belonging to an Application - such as listing all tokens or creating a new token.

  • Application Key
    Contains all the actions that can be performed against a single Application Key - for instance, getting info on a single key or revoking a key.

  • Application Keys
    Contains all of the actions that can be performed against the collection of Application Keys belonging to an Application - such as listing all keys or creating a new key.

  • Audit Log
    Contains all of the actions that can be performed against a single Audit Log that belongs to an organization - such as viewing a log.

  • Audit Logs
    Contains all of the actions that can be performed against the set of Audit Logs that belong to an organization - such as listing the logs.

  • Auth
    Contains the actions used for authenticating against the api, either as a user or as a device. The result of authentication calls contain the api access token needed for authenticated calls - see the examples for more details.

  • Dashboard
    Contains all of the actions that can be performed against a single Dashboard, which include things like getting info on a dashboard or modifying a dashboard.

  • Dashboards
    Contains all of the actions that can be performed against the set of Dashboards that the currently authenticated user has access to - such as listing the dashboards or creating a new dashboard.

  • Data
    Contains the actions for querying against historical Device data across an Application.

  • Data Table
    Contains all the actions that can be performed against a single Data Table - for instance, getting info on a single data table or modifying the columns of a data table.

  • Data Tables
    Contains all of the actions that can be performed against the collection of Data Tables belonging to an Application - such as listing all data tables or creating a new data table.

  • Data Table Row
    Contains all the actions that can be performed against a single row inside of a Data Table - for instance, getting the contents of a row, or modifying a row.

  • Data Table Rows
    Contains all of the actions that can be performed against the collection of rows that make up a Data Table - such as querying for rows in that table, or adding a new row to the table.

  • Device
    Contains all the actions that can be performed against a single Device - for instance, getting info on a single device or reporting the current state of a device.

  • Devices
    Contains all of the actions that can be performed against the collection of Devices belonging to an Application - such as listing all devices or sending a command to a set of devices.

  • Device Recipe
    Contains all the actions that can be performed against a single Device Recipe, which include things like removing a device recipe or creating a device from a device recipe.

  • Device Recipes
    Contains all the actions that can be performed against the collection of Device Recipes belonging to an Application - such as listing recipes or creating a new recipe.

  • Edge Deployments
    Contains all the actions that can be performed against the collection of Edge Deployments belonging to an Application - such as listing deployments or creating a new deployment.

  • Event
    Contains all the actions that can be performed against a single Event, such as commenting on or changing the state of an event.

  • Events
    Contains all the actions that can be performed against the collection of Events belonging to an Application - such as listing open events or creating a new event.

  • Experience
    Contains all the actions that can be performed against an application Experience, such as bootstrapping or clearing resources.

  • Experience Domain
    Contains all the actions that can be performed against a single Experience Domain, such as updating SSL certificate information.

  • Experience Domains
    Contains all the actions that can be performed against the collection of Experience Domains belonging to an Application - such as listing domains or creating a new domain.

  • Experience Endpoint
    Contains all the actions that can be performed against a single Experience Endpoint, such as updating route information.

  • Experience Endpoints
    Contains all the actions that can be performed against the collection of Experience Endpoints belonging to an Application - such as listing endpoints or creating a new endpoint.

  • Experience Group
    Contains all the actions that can be performed against a single Experience Group, such as updating member information.

  • Experience Groups
    Contains all the actions that can be performed against the collection of Experience Groups belonging to an Application - such as listing groups or creating a new group.

  • Experience Slug
    Contains all the actions that can be performed against a single Experience Slug, such as changing the associated version.

  • Experience Slugs
    Contains all the actions that can be performed against the collection of Experience Slugs belonging to an Application - such as listing slugs or creating a new slug.

  • Experience User
    Contains all the actions that can be performed against a single Experience User, such as changing their email or password.

  • Experience Users
    Contains all the actions that can be performed against the collection of Experience Users belonging to an Application - such as listing users or creating a new user.

  • Experience Version
    Contains all the actions that can be performed against a single Experience Version, such as modifying the description.

  • Experience Versions
    Contains all the actions that can be performed against the collection of Experience Versions belonging to an Application - such as listing versions or creating a new versions.

  • Experience View
    Contains all the actions that can be performed against a single Experience View, such as modifying the body template.

  • Experience Views
    Contains all the actions that can be performed against the collection of Experience Views belonging to an Application - such as listing views or creating a new view.

  • File
    Contains all the actions that can be performed against a single File, such as moving, renaming, or deleting.

  • Files
    Contains all the actions that can be performed against the collection of Files belonging to an Application - such as listing files or uploading a new file.

  • Integration
    Contains all the actions that can be performed against a single Integration, which include things like removing an integration or updating integration configuration.

  • Integrations
    Contains all the actions that can be performed against the collection of Integrations belonging to an Application - such as listing integrations or creating a new integration.

  • Me
    Contains the actions for operating against the currently authenticated User such as changing the password or linking against external services.

  • Organization
    Contains all the actions that can be performed against a single Organization, things like inviting a user to the organization, or modifying the organization.

  • Organizations
    Contains all of the actions that can be performed against the set of Organizations that the currently authenticated user has access to - such as listing the organizations or creating a new organization.

  • Organization Invites
    Contains all of the actions that can be performed against a invitation to an organization, such as accepting the invitation.

  • Webhook
    Contains all the actions that can be performed against a single Webhook, for instance modifying the verification settings or removing the webhook.

  • Webhooks
    Contains all the actions that can be performed against the collection of Webhooks belonging to an Application - such as listing the webhooks or creating a new webhook.

  • Workflow
    Contains all the actions that can be performed against a single Workflow, such as enabling or disabling a workflow, or triggering a virtual button in the workflow.

  • Workflows
    Contains all the actions that can be performed against the collection ofWorkflows belonging to an Application - such as listing the workflows or creating a new workflow.

  • Workflow Version
    Contains all the actions that can be performed against a single Workflow Version, such as enabling or disabling a workflow version, or updating the version notes.

  • Workflow Versions
    Contains all the actions that can be performed against the collection of Workflow Versions belonging to a Workflow - such as listing the versions or creating a new version.

Throttles And Limits

The following API endpoints have specific throttling: