Atmosphere IoT Platform API v2 (2.0.0)

Download OpenAPI specification:Download

This documentation is specific to our HTTP API. See our full documentation hub for details on the Atmosphere IoT Platform.

Introduction

The Atmosphere v2 HTTP API is based on OpenAPI v3, making it easy to use. It follows RESTful best practices and drastically simplifies the process of registering a new device. Adding a device is accomplished as a POST /v2/devices, and exchanging data with the platform from your embedded device is accomplished via Device Events and Cloud Events (/events/*). The v2 API also provides full capabilities for managing Organizations and Users.

The JSON format of API specification is available at https://platform.atmosphereiot.com/spec. Tools such as Postman can import this URL and automatically generate a comprehensive menu of available operations, with parameters and examples. Just plug in your API key or device token and start submitting requests. We even use the spec in combination with swagger-js to automatically generate code in the Atmosphere IoT web UI.

Rate Limits

Rate limits are applied to all HTTP requests. They are subject to change, and may vary according to the authentication mechanism being used in the request (i.e. per-user if using jwt or apiToken, or per-device if using a deviceToken.

Note that the user interface also uses this API. So both browser usage and direct API usage apply to per-user rate limits.

The following HTTP response headers can be used for determining the specific rate limits that have been applied:

Response Header	Description
x-ratelimit-limit	The number of requests allowed in the current period.
x-ratelimit-reset	The time at which the current period will expire. This is specified as a unix timestamp.
x-ratelimit-remaining	The number of allowed requests remaining between now and the expiration time.

Getting More Help

Still have questions? Our Forums are the best way to interact with other users and Atmosphere IoT engineers. https://forum.atmosphereiot.com/

Authentication

jwt

This is the preferred authentication scheme, offering the most robust security. A call to /auth/login returns a JSON Web Token (https://jwt.io/), which is then used in subsequent requests.

The JWT issued will expire in 15 minutes, after which time the client should request a new token via /auth/refreshToken (preferred) or via /auth/login.

Security Scheme Type	HTTP
HTTP Authorization Scheme	bearer
Bearer format	"JWT"

refreshToken

Only supported for use with the /auth/refreshToken API method, this is the preferred mechanism for refreshing a JWT that has expired. Clients that support cookies will also receive a cookie containing a refreshToken during a call to /auth/login. This cookie is to be used for fetching a new JWT when the current one expires. This refresh token expires in 14 days, after which the user must login again. Use of this process ensures that sensitive passwords or API keys are transmitted as infrequently as possible.

Security Scheme Type	API Key
Cookie parameter name:	refreshToken

apiKey

Users may create an API Key for themselves in their user profile settings. These API keys are functionally equivalent to a password, and should be treated as such. Setting this header on each API call is the most convenient mechanism for authenticating with the API. However, this results in transmitting your sensitive key with each request. The recommended approach for API integration is to only use your API key to call /auth/login to fetch a JWT, and then use the JWT for subsequent requests, until it expires. If your client supports cookies, we also recommend using the refreshToken to fetch a new JWT, so that your API Key is only rarely transmitted.

Security Scheme Type	API Key
Header parameter name:	api_auth_token

apiKeyAlt

Identical to apiKey, except that the key is set in the authorization header.

Security Scheme Type	API Key
Header parameter name:	authorization

deviceToken

When a device is created, a security token is generated for that device. This is intended to be used by the device for authentication, and should be kept secret. This authentication scheme is limited to specific APIs, such as Events. Look for where deviceToken is listed under the API's "AUTHORIZATIONS" section.

Security Scheme Type	API Key
Header parameter name:	cloud

auth

Authentication, security tokens, login/logout, etc

Register

Creates a new user. Requires that password and passwordConfirmation are set.

Request Body schema: application/json

username required	string Username for the user. Must be globally unique. May be same as email.
password	string User's plaintext password. Only used for user creation.
passwordConfirmation	string User's plaintext password. Only used for user creation. Must match password field.
firstName required	string User's given name.
lastName required	string User's surname.
email required	string <email> Email address for the user. Must be globally unique.
company required	string Company name for the user.
role required	string The user's role.
organizationId	string
tosHash	string
language	string

Responses

Request samples

Payload

Content type

application/json

{"username": "string",
"password": "string",
"passwordConfirmation": "string",
"firstName": "string",
"lastName": "string",
"email": "user@example.com",
"company": "string",
"role": "developer",
"organizationId": "string",
"tosHash": "string",
"language": "string"
}

Response samples

201
400
401

Content type

application/json

{"id": "string",
"username": "string",
"email": "user@example.com",
"role": "technican",
"tosHash": "string",
"firstName": "string",
"lastName": "string",
"company": "string",
"jobTitle": "string",
"language": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"lastActive": "2019-08-24T14:15:22Z",
"preferences": {"notifications": {"accountNotifications": {"inapp": true,
"email": false
},
"systemNotification": {"inapp": true,
"email": false
},
"deviceNotification": {"inapp": true,
"email": false
}
}
},
"imageUrl": "/users/{id}/image.png",
"organizationName": "string",
"organizationId": "string",
"disabled": true
}

Verify Account

Verify your account with the verification token sent via email.

path Parameters

nonce

required

string

Account Verification Token

Responses

Response samples

404

Content type

application/json

{"message": "Requested Resource Not Found"
}

Login

Submit username/password, and receive a JWT in the response for making further requests to the rest of the API.

Request Body schema: application/json

usernameOrEmail required	string Can either be a username or e-mail address belonging to an account on the platform.
password required	string <password>

Responses

Request samples

Payload

Content type

application/json

{"usernameOrEmail": "string",
"password": "pa$$word"
}

Response samples

201
401

Content type

application/json

{"jwtToken": "string",
"jwtTokenExpiry": "string"
}

Log out of the platform

Log out of the platform, and invalidate the current user's JWT/refresh tokens. It is the caller's responsibility to provide the tokens which need to be invalidated.

Authorizations:

jwtrefreshToken

Responses

Response samples

401

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

Refresh JWT

Authenticates the caller using refreshToken authentication, and returns a JWT, which may be used for subsequent calls to the API.

Authorizations:

refreshToken

Responses

Response samples

201
401

Content type

application/json

{"jwtToken": "string",
"jwtTokenExpiry": "string"
}

Current User

Returns the currently logged-in user.

Authorizations:

jwtapiKeyapiKeyAlt

Responses

Response samples

200
401

Content type

application/json

{"id": "string",
"username": "string",
"email": "user@example.com",
"role": "technican",
"tosHash": "string",
"firstName": "string",
"lastName": "string",
"company": "string",
"jobTitle": "string",
"language": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"lastActive": "2019-08-24T14:15:22Z",
"preferences": {"notifications": {"accountNotifications": {"inapp": true,
"email": false
},
"systemNotification": {"inapp": true,
"email": false
},
"deviceNotification": {"inapp": true,
"email": false
}
}
},
"imageUrl": "/users/{id}/image.png",
"organizationName": "string",
"organizationId": "string",
"disabled": true
}

data

Your project design can use Storage Elements to persist data according to your needs. Each such Storage Element effectively represents its own time-series database. Individual data records stored in a Storage Element are queried via the data API. There is also a specialized API to fetch a summary of the "last values" stored in a Storage Element, in the event that you do not save the same payload every time the element is triggered.

Note that the data you store in a Storage Element is not necessarily the same as the raw data your device sends to the platform. The raw data is captured as an Event, but may be transformed by your project before being stored in a Storage Element.

List stored values in a Storage Element

List stored values in a Storage Element.

Values are sorted in reverse-time-order (i.e. newest first), by default. The sortBy parameter is supported for any value present in the payload. For example, if you have payloads that look like { payload: { temp: 55, humidity: 67 } and you want to sort by temp, the query parameter would be sortBy=payload.temp.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id required	string Resource ID
elementName required	string The name of an element

query Parameters

page

integer <int32> >= 1

Default: 1

Example: page=5

desired page for pagination

limit

integer <int32> [ 1 .. 10000 ]

Default: 100

Example: limit=10

max records to return for pagination

from

string <date-time>

Example: from=2020-05-11T15:51:06Z

Start date of resources. Inclusive.

to

string <date-time>

Example: to=2020-05-12T15:51:06Z

End date of resources. Not inclusive.

sortBy

Array of strings

Example: sortBy=field1&sortBy=-field2

Sort the results according to this value. Allowed sort fields varies according to the entity. Optionally, the sort order may be specified by prepending a + for ascending and - for descending. This parameter may be specified multiple times, which will be processed in subsequent order (i.e. first supplied parameter will be primary sort, second supplied parameter will be secondary sort, etc).

filter

object

Filter the results according to the options given. All filter parameters are logically "ANDed" together. Each filter parameter requires:

the data field to match
the operation to perform
the value to match

The format is filter[{field}][{operator}]={value}

Supported operators

Operator	Description
`eq`	Matches values that are equal to a specified value.
`ne`	Matches all values that are not equal to a specified value.
`lt`	Matches values that are less than a specified value.
`lte`	Matches values that are less than or equal to a specified value.
`gt`	Matches values that are greater than a specified value.
`gte`	Matches values that are greater than or equal to a specified value.
`in`	Matches any of the values specified in a comma-separated array of values.
`nin`	Matches none of the values specified in a comma-separated array of values.

Some examples:

Description	Query Parameters
where `temp` is greater than `55`	`?filter[temp][gt]=55`
where `temp` is greater than `55` AND the `humidity` is less than `67`	`?filter[temp][gt]=55&filter[humidity][lt]=67`

Responses

Response samples

200
400
401
404

Content type

application/json

{"meta": {"totalDocs": 0,
"page": 0,
"limit": 0,
"hasPrevPage": true,
"hasNextPage": true,
"totalPages": 0
},
"data": [{"id": "5f749d9cfa570d0025b6f20b",
"createdAt": "2019-08-24T14:15:22Z",
"deviceId": "5f88b9fb2856480025cb48bd",
"elementName": "CloudStorage1",
"payload": {"temp": "55"
}
}
]
}

A storage element's "last values".

Fetches a "composite" of the most recent data records for a specific storage element on a device. If your device sends multiple readings, but not always at the same time, you can use this API to see the most recent values for all the keys that have been provided.

Example: A device that sends a temperature reading of {"temp": "55"} and then later sends a humidity reading of {"humidity": "67"} would have a "last values" of {"temp": "55", "humidity": "67"}.

Note: This API is intended for cases where you store a JSON data type that is an object-literal (i.e. {"foo": "bar"}). It is useful when your device might not send the full set of values with every Device Event. If you store other JSON data types (i.e. null, true, false, [{a:b},{c:d}], "astring"), this API will always return the most recent value stored.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id required	string Resource ID
elementName required	string The name of an element

Responses

Response samples

200
401
404

Content type

application/json

{"updatedAt": "2019-08-24T14:15:22Z",
"deviceId": "5f88b9fb2856480025cb48bd",
"elementName": "CloudStorage1",
"values": {"temp": "55"
}
}

devices

Operations concerning devices

List devices

Fetches devices according to the parameters given.

Supported sort fields:

name (default)
description

Authorizations:

jwtapiKeyapiKeyAlt

query Parameters

	string or integer Default: 1 Maximum depth of the tree to return results. Default is 1. "all" will return all results.
page	integer <int32> >= 1 Default: 1 Example: page=5 desired page for pagination
limit	integer <int32> [ 1 .. 10000 ] Default: 100 Example: limit=10 max records to return for pagination
organizationId	string organization ID query
searchText	string Example: searchText=SearchString Filters the results according to entries that match the supplied text. The specific fields searched vary according to the entity.
sortBy	Array of strings Example: sortBy=field1&sortBy=-field2 Sort the results according to this value. Allowed sort fields varies according to the entity. Optionally, the sort order may be specified by prepending a `+` for ascending and `-` for descending. This parameter may be specified multiple times, which will be processed in subsequent order (i.e. first supplied parameter will be primary sort, second supplied parameter will be secondary sort, etc).
lastValues	string Example: lastValues=all \|\| TemperatureStorage%2CHumidityStorage Include latest device data values in query. Similar to /devices/{id}/last Providing 'all' will return the lastest data values from all the storage elements of the device(s). Supports comma separated values to define which datasets are returned, must be URI encoded.
entityList	Array of strings Example: entityList=60b8ea2f8535950026b6ed99,60b8ea2f8535950026b6ed97,60b8ea1670cd970025eeeceb,60b8e9e28535950026b6ed4f,60b8e9e28535950026b6ed49,60b8e9e28535950026b6ed51,60b8e90a8cfe3200253b017b,60b8ea1670cd970025eeece9,60b8ea1670cd970025eeeced,60b8e90a8cfe3200253b0173,60d0e2778770a10025ead3f7 Query only a list of the entity ID's provided. For example, a subset of devices, users, organizations so on and so forth may be returned and filtered from the query back to the client using this parameter.

Responses

Response samples

200
401

Content type

application/json

{"meta": {"totalDocs": 0,
"page": 0,
"limit": 0,
"hasPrevPage": true,
"hasNextPage": true,
"totalPages": 0
},
"data": [{"id": "string",
"name": "string",
"createdBy": "string",
"uuid": "string",
"projectUuid": "stringstringstringstring",
"versionUuid": "string",
"protocol": "ble",
"protocols": ["string"
],
"lastValues": [{ }
],
"lastActive": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"meta": { },
"statusText": "none",
"statusInt": 6,
"description": "This is a device",
"streetAddress": {"address": "400 Park Avenue",
"city": "New York",
"region": "NY",
"postalCode": 12000,
"country": "United States"
},
"imageUrl": "/v2/devices/{id}/image.png",
"organizationName": "string",
"organizationId": "stringstringstringstring"
}
]
}

Create a new device

Create a new device, responds with the newly created device

Authorizations:

jwtapiKeyapiKeyAlt

Request Body schema: application/json

name required	string [ 1 .. 80 ] characters
projectUuid required	string [ 24 .. 36 ] characters
versionUuid	string <= 36 characters Nullable
protocol	string <= 20 characters Nullable
protocols	Array of strings >= 0 items
meta	object Deprecated Default: {}
description	string [ 0 .. 200 ] characters
	object
organizationId	string [ 24 .. 36 ] characters

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"projectUuid": "stringstringstringstring",
"versionUuid": "string",
"protocol": "ble",
"protocols": ["string"
],
"meta": { },
"description": "This is a device",
"streetAddress": {"address": "400 Park Avenue",
"city": "New York",
"region": "NY",
"postalCode": 12000,
"country": "United States"
},
"organizationId": "stringstringstringstring"
}

Response samples

201
400
401

Content type

application/json

{"id": "string",
"name": "string",
"createdBy": "string",
"uuid": "string",
"projectUuid": "stringstringstringstring",
"versionUuid": "string",
"protocol": "ble",
"protocols": ["string"
],
"lastValues": [{ }
],
"lastActive": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"meta": { },
"statusText": "none",
"statusInt": 6,
"description": "This is a device",
"streetAddress": {"address": "400 Park Avenue",
"city": "New York",
"region": "NY",
"postalCode": 12000,
"country": "United States"
},
"imageUrl": "/v2/devices/{id}/image.png",
"organizationName": "string",
"organizationId": "stringstringstringstring",
"token": "string"
}

Fetch all devices along with their locations

Returns the device locations.

Authorizations:

jwtapiKeyapiKeyAlt

query Parameters

organizationId	string organization ID query
	string or integer Default: 1 Maximum depth of the tree to return results. Default is 1. "all" will return all results.

Responses

Response samples

200
401
404

Content type

application/json

{"meta": {"totalDocs": 0,
"page": 0,
"limit": 0,
"hasPrevPage": true,
"hasNextPage": true,
"totalPages": 0
},
"data": [{"id": "string",
"uuid": "string",
"organizationId": "stringstringstringstring",
"name": "string",
"latitude": 0,
"longitude": 0,
"statusInt": 6,
"statusText": "none"
}
]
}

Fetch a device

Returns the device with the specified ID.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

query Parameters

lastValues

string

Example: lastValues=all || TemperatureStorage%2CHumidityStorage

Include latest device data values in query. Similar to /devices/{id}/last Providing 'all' will return the lastest data values from all the storage elements of the device(s). Supports comma separated values to define which datasets are returned, must be URI encoded.

Responses

Response samples

200
401
404

Content type

application/json

{"id": "string",
"name": "string",
"createdBy": "string",
"uuid": "string",
"projectUuid": "stringstringstringstring",
"versionUuid": "string",
"protocol": "ble",
"protocols": ["string"
],
"lastValues": [{ }
],
"lastActive": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"meta": { },
"statusText": "none",
"statusInt": 6,
"description": "This is a device",
"streetAddress": {"address": "400 Park Avenue",
"city": "New York",
"region": "NY",
"postalCode": 12000,
"country": "United States"
},
"imageUrl": "/v2/devices/{id}/image.png",
"organizationName": "string",
"organizationId": "stringstringstringstring"
}

Update a device

Updates the device with the specified ID and returns the updated version.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

query Parameters

lastValues

string

Example: lastValues=all || TemperatureStorage%2CHumidityStorage

Include latest device data values in query. Similar to /devices/{id}/last Providing 'all' will return the lastest data values from all the storage elements of the device(s). Supports comma separated values to define which datasets are returned, must be URI encoded.

Request Body schema: application/json

name required	string [ 1 .. 80 ] characters
projectUuid required	string [ 24 .. 36 ] characters
versionUuid	string <= 36 characters Nullable
protocol	string <= 20 characters Nullable
protocols	Array of strings >= 0 items
meta	object Deprecated Default: {}
description	string [ 0 .. 200 ] characters
	object
organizationId	string [ 24 .. 36 ] characters

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"projectUuid": "stringstringstringstring",
"versionUuid": "string",
"protocol": "ble",
"protocols": ["string"
],
"meta": { },
"description": "This is a device",
"streetAddress": {"address": "400 Park Avenue",
"city": "New York",
"region": "NY",
"postalCode": 12000,
"country": "United States"
},
"organizationId": "stringstringstringstring"
}

Response samples

200
401
404

Content type

application/json

{"id": "string",
"name": "string",
"createdBy": "string",
"uuid": "string",
"projectUuid": "stringstringstringstring",
"versionUuid": "string",
"protocol": "ble",
"protocols": ["string"
],
"lastValues": [{ }
],
"lastActive": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"meta": { },
"statusText": "none",
"statusInt": 6,
"description": "This is a device",
"streetAddress": {"address": "400 Park Avenue",
"city": "New York",
"region": "NY",
"postalCode": 12000,
"country": "United States"
},
"imageUrl": "/v2/devices/{id}/image.png",
"organizationName": "string",
"organizationId": "stringstringstringstring"
}

Delete a device

Deletes the device with the specified ID.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

query Parameters

lastValues

string

Example: lastValues=all || TemperatureStorage%2CHumidityStorage

Include latest device data values in query. Similar to /devices/{id}/last Providing 'all' will return the lastest data values from all the storage elements of the device(s). Supports comma separated values to define which datasets are returned, must be URI encoded.

Responses

Response samples

401
404

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

Fetch Events for a device

Queries the Event history for a device (CloudEvents and DeviceEvents). This is primarily useful for troubleshooting, and is not intended for primary data storage.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

deviceId

required

string

Resource ID

query Parameters

deviceEvents	boolean Default: true Include Device Events (events sent from a device to the cloud) in the response.
cloudEvents	boolean Default: true Include Cloud Events (events sent from the cloud to a device) in the response.
limit	integer <int32> [ 1 .. 10000 ] Default: 100 Example: limit=10 max records to return for pagination
page	integer <int32> >= 1 Default: 1 Example: page=5 desired page for pagination
from	string <date-time> Example: from=2020-05-11T15:51:06Z Start date of resources. Inclusive.
to	string <date-time> Example: to=2020-05-12T15:51:06Z End date of resources. Not inclusive.

Responses

Response samples

200
401
404

Content type

application/json

{"meta": {"totalDocs": 0,
"page": 0,
"limit": 0,
"hasPrevPage": true,
"hasNextPage": true,
"totalPages": 0
},
"data": [{"id": "string",
"type": "string",
"deviceId": "string",
"elementName": "string",
"payload": { },
"receivedAt": "2019-08-24T14:15:22Z"
}
]
}

Fetch an Event for a device

Returns the event with the specified ID.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

deviceId required	string Resource ID
id required	string Resource ID

Responses

Response samples

200
401
404

Content type

application/json

{"id": "string",
"type": "string",
"deviceId": "string",
"elementName": "string",
"payload": { }
}

Fetch a device's image

Returns the device image

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Responses

Response samples

401
404

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

Update a Device's image

Updates the image for the specified ID.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Request Body schema: text/plain

string (Image) ^data:image\/(png|jpg|jpeg|gif|svg|webp);base...

Responses

Response samples

401
404

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

Delete a device's image

Deletes the image set set for the specified device ID.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Responses

Response samples

401
404

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

Change settings for multiple devices

Devices settings may be updated for a plethora of devices

Authorizations:

jwtapiKeyapiKeyAlt

Request Body schema: application/json

Array ()

Any of

deviceId	string The device ID that the device setting is associated with.
name	string [ 1 .. 128 ] characters Non-human friendly name of the setting, a unique identifier that is tied to the device's project.
value	any The value of the configured device setting. Can be any of the listed types, but will resolve to an key-value pair where the key is the "name" of the input when stored.

Responses

Request samples

Payload

Content type

application/json

[{"deviceId": "6108da42fdb2591be2304275",
"name": "CloudDeviceSetting1",
"value": "Text value here"
},
{"deviceId": "6108da42fdb2591be2304264",
"name": "CloudDeviceSetting2",
"value": 33
},
{"deviceId": "6108da42fdb2591be2304253",
"name": "CloudDeviceSetting3",
"value": false
}
]

Response samples

200
401
404

Content type

application/json

{"data": [{"id": "61094cd684eff421ddf45ae0",
"deviceId": "61094cd284eff421ddf45a50",
"createdAt": "2021-08-03T14:04:02.982Z",
"updatedAt": "2021-08-03T14:04:06.117Z",
"name": "Vietnam_0d4c986b-6e4e-4e4d-8f16-0bca022c8f5c",
"title": "web-readiness",
"description": "Implementation",
"inputType": "text",
"inputTypeProperties": ["Object"
],
"listOrder": 7,
"value": "\"Liaison\"",
"defaultValue": "\"Human\"",
"changedById": "61094cd284eff421ddf45a47"
},
{"id": "61094cd684eff421ddf45ae1",
"deviceId": "61094cd284eff421ddf45a50",
"createdAt": "2021-08-02T14:04:02.985Z",
"updatedAt": "2021-08-03T14:04:06.119Z",
"name": "payment_8bb97798-528e-470d-95fa-42e18ca2d864",
"title": "Grocery",
"description": "Principal USB connect",
"inputType": "toggle",
"inputTypeProperties": ["Object"
],
"listOrder": 16,
"value": true,
"defaultValue": false,
"changedById": "61094cd284eff421ddf45a47"
},
{"id": "61094cd684eff421ddf45ae2",
"deviceId": "61094cd284eff421ddf45a50",
"createdAt": "2021-08-01T14:04:02.987Z",
"updatedAt": "2021-08-03T14:04:06.122Z",
"name": "circuit_76b27dda-512d-4afe-9427-0ab951d60536",
"title": "benchmark",
"description": "calculating",
"inputType": "number",
"inputTypeProperties": ["Object"
],
"listOrder": 26,
"value": 59,
"defaultValue": 50,
"changedById": "61094cd284eff421ddf45a47"
}
],
"errors": [{"message": "deviceId: 61094d5d2442f0226e65f9c0 failed to save updated setting \"Generic Plastic Chicken\" with value -2 as the setting is not modifiable by user: Everette.Kautzer"
},
{"message": "deviceId: 61094d5d2442f0226e65f9c5 failed to save updated setting \"virtual_ab6b67aa-8955-4a84-bb98-6551817fd68b\" with value {\"cherries\": 2} as the setting is not modifiable by user: Everette.Kautzer"
}
]
}

Get default settings for a list of devices

When configuring device settings en masse, it is useful to know what the default settings are for each type of device. The endpoint will analyze the unique projects from the list of devices and return the default settings for that project.

Authorizations:

jwtapiKeyapiKeyAlt

Request Body schema: application/json

Array ()

Any of

string (deviceId)

Responses

Request samples

Payload

Content type

application/json

["6108da42fdb2591be2304275",
"6108da42fdb2591be2304264",
"6108da42fdb2591be2304253"
]

Response samples

200
401
404

Content type

application/json

{"errors": [{"message": "No available default settings",
"projectUuid": "f7ae7a43-8132-483c-9193-0ecf8f00a942",
"versionUuid": "8485e54e-4020-4b06-94e7-997ad2554176"
}
],
"data": [{"projectUuid": "a591a110-3f58-4512-bb03-a5b95f9437d8",
"versionUuid": "295c8c00-e8ae-49fc-9eb0-948aa86224d0",
"deviceIdList": ["6103aa263aa92a0025d509b9",
"61035bbc3aa92a0025d48861",
"61046de31d009a00266bf732",
"61039fda8699ef0026fc23fe",
"61046de88bebd900253ca630",
"61031e314bab6600261cfa5b",
"61035d723aa92a0025d48c2d",
"6103513c789cc10026dab9b9",
"61046ddb264d6100250eb430",
"6103315242be7e00260ec1f9",
"6103325ac4f1a00025e2b8a3",
"6103f4e342be7e00260fdb17",
"61046ddfb067790026f77e25",
"6103276c3aa92a0025d42b2f",
"61046d908bebd900253ca2b6",
"6105b8878bebd900253fe360",
"60c3f824463d0d0026f86302"
],
"defaultSettings": [{"listOrder": 0,
"inputType": "text",
"inputTypeProperties": null,
"defaultValue": "Test",
"_id": "611aa908db1fed2fcf258013",
"title": "",
"description": ""
},
{"listOrder": 0,
"inputType": "number",
"defaultValue": "2",
"_id": "611aa908db1fed2fcf258014",
"title": "",
"description": ""
},
{"listOrder": 0,
"inputType": "toggle",
"defaultValue": "false",
"_id": "611aa908db1fed2fcf258015",
"title": "",
"description": ""
}
]
}
]
}

Fetch a device's settings

Returns the device settings

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

query Parameters

page	integer <int32> >= 1 Default: 1 Example: page=5 desired page for pagination
limit	integer <int32> [ 1 .. 10000 ] Default: 100 Example: limit=10 max records to return for pagination
sortBy	Array of strings Example: sortBy=field1&sortBy=-field2 Sort the results according to this value. Allowed sort fields varies according to the entity. Optionally, the sort order may be specified by prepending a `+` for ascending and `-` for descending. This parameter may be specified multiple times, which will be processed in subsequent order (i.e. first supplied parameter will be primary sort, second supplied parameter will be secondary sort, etc).

Responses

Response samples

200
401
404

Content type

application/json

{"meta": {"totalDocs": 0,
"page": 0,
"limit": 0,
"hasPrevPage": true,
"hasNextPage": true,
"totalPages": 0
},
"data": [{"id": "string",
"deviceId": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"changedAt": "2019-08-24T14:15:22Z",
"changedToId": "string",
"changedById": "string",
"name": "string",
"title": {"en-US": "Max threshold",
"es": "Umbral máximo"
},
"description": "{\n    'en-US': 'Defines the upper limit of the value before alarms are triggered',\n    'es': 'Define el límite superior del valor antes de que se activen las alarmas',\n}\n",
"inputType": "text",
"inputTypeProperties": { },
"value": {"textInput1": "This is an example value"
},
"defaultValue": {"textInput1": "This is an example value"
},
"listOrder": 0
}
]
}

Reset all of a device's settings

Resets all device settings

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Responses

Response samples

401
404

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

Fetch a device setting by name

Returns the device setting by name

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id required	string Resource ID
settingName required	string The name of a device setting

Responses

Response samples

200
401
404

Content type

application/json

{"id": "string",
"deviceId": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"changedAt": "2019-08-24T14:15:22Z",
"changedToId": "string",
"changedById": "string",
"name": "string",
"title": {"en-US": "Max threshold",
"es": "Umbral máximo"
},
"description": "{\n    'en-US': 'Defines the upper limit of the value before alarms are triggered',\n    'es': 'Define el límite superior del valor antes de que se activen las alarmas',\n}\n",
"inputType": "text",
"inputTypeProperties": { },
"value": {"textInput1": "This is an example value"
},
"defaultValue": {"textInput1": "This is an example value"
},
"listOrder": 0
}

Update a device setting by name

Updates the device setting by name, the request body is essential.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id required	string Resource ID
settingName required	string The name of a device setting

Request Body schema: application/json

In order to keep things as simple as possible for device settings, this API is intended to support a variety of values. Thus, there are no envelopes, wrappers, or other data structures required. Any valid JSON supported by OpenAPI 3 may be passed as the body. OpenAPI 3 supports all JSON Schema data types EXCEPT null. If you have a need to support a content type other than application/json, please contact support and let us know.

Any of

string

Responses

Request samples

Payload

Content type

application/json

{"foo": "bar"
}

Response samples

200
401
404

Content type

application/json

{"id": "string",
"deviceId": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"changedAt": "2019-08-24T14:15:22Z",
"changedToId": "string",
"changedById": "string",
"name": "string",
"title": {"en-US": "Max threshold",
"es": "Umbral máximo"
},
"description": "{\n    'en-US': 'Defines the upper limit of the value before alarms are triggered',\n    'es': 'Define el límite superior del valor antes de que se activen las alarmas',\n}\n",
"inputType": "text",
"inputTypeProperties": { },
"value": {"textInput1": "This is an example value"
},
"defaultValue": {"textInput1": "This is an example value"
},
"listOrder": 0
}

Reset a device setting by name

Resets the device setting by name

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id required	string Resource ID
settingName required	string The name of a device setting

Responses

Response samples

401
404

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

Fetch the history of changes applied to the device's settings

Returns the history of all the device settings

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

query Parameters

page	integer <int32> >= 1 Default: 1 Example: page=5 desired page for pagination
limit	integer <int32> [ 1 .. 10000 ] Default: 100 Example: limit=10 max records to return for pagination
sortBy	Array of strings Example: sortBy=field1&sortBy=-field2 Sort the results according to this value. Allowed sort fields varies according to the entity. Optionally, the sort order may be specified by prepending a `+` for ascending and `-` for descending. This parameter may be specified multiple times, which will be processed in subsequent order (i.e. first supplied parameter will be primary sort, second supplied parameter will be secondary sort, etc).

Responses

Response samples

200
401
404

Content type

application/json

{"meta": {"totalDocs": 0,
"page": 0,
"limit": 0,
"hasPrevPage": true,
"hasNextPage": true,
"totalPages": 0
},
"data": [{"id": "string",
"deviceId": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"changedAt": "2019-08-24T14:15:22Z",
"changedToId": "string",
"changedById": "string",
"name": "string",
"title": {"en-US": "Max threshold",
"es": "Umbral máximo"
},
"description": "{\n    'en-US': 'Defines the upper limit of the value before alarms are triggered',\n    'es': 'Define el límite superior del valor antes de que se activen las alarmas',\n}\n",
"inputType": "text",
"inputTypeProperties": { },
"value": {"textInput1": "This is an example value"
},
"defaultValue": {"textInput1": "This is an example value"
},
"listOrder": 0
}
]
}

events

Events are the primary data structures that a device uses to exchange data with the Atmosphere cloud platform. This is comprised of "Device Events", which are events sent by the device to the cloud, and "Cloud Events", which are events sent by the cloud to a device.

For devices using HTTP as their communication protocol, the /events API is the primary interface to send and receive data. It is optimized to make it as easy as possible for your embedded device to communicate with Atmosphere over HTTP.

Regardless of what protocol your device uses to communicate with Atmosphere (HTTP, SigFox, TTN, etc), a device's Event history may be accessed under /devices/{deviceId}/events. Events are retained and accessible for a period of six months. This is primarily useful for troubleshooting, and is not intended for primary data storage.

Note that an "Event" is fundamentally different than a "Stored Value". DeviceEvents are the raw data sent by your device to the cloud. Your project design may filter, transform, or perform other logic when a device sends data. Thus, what your project stores in a Storage Element (/devices/{deviceId}/data) may be entirely different than the raw data your device sends or receives (/devices/{deviceId}/events).

Post an Event for a device

Posts a DeviceEvent for a device, which will then be sent for processing by the Cloud Plane of the project associated with that device. This is the primary API for devices to send data to the cloud via HTTP.

If a device token is used for authentication, The device ID is determined from the token, and the deviceId query parameter is ignored. If another form of authentication is used, the deviceId parameter must be provided.

Authorizations:

jwtapiKeyapiKeyAltdeviceToken

query Parameters

deviceId	string ID of the device sending the data. Only required if `token` authentication is NOT used. If `token` authentication is used, the device ID will be derived from the token, and this parameter will be ignored.
elementName	string Element Name

Request Body schema: application/json

In order to keep things as simple as possible for embedded devices, this API is intended to support whatever payload makes sense for your application. Thus, there are no envelopes, wrappers, or other data structures required. Any valid JSON supported by OpenAPI 3 may be passed as the body. OpenAPI 3 supports all JSON Schema data types EXCEPT null.

Currently, only application/json is supported. For binary data payloads, we recommend Base64 encoding it, and sending it as a string. But if you have a need to support a content type other than application/json, please contact support and let us know.

Any of

object Nullable

Responses

Request samples

Payload

Content type

application/json

{"foo": "bar"
}

Response samples

201
400
401

Content type

application/json

{"id": "5f3173b60fc786002524e2bd"
}

Fetch multiple queued cloud events for a device

Returns the next queued CloudEvent for the device. Returns 204 NO CONTENT if there are none.

CloudEvents are a queue of messages for a device. By default, they are dequeued when accessed. If you wish to access events in the queue without removing them from the queue (a "peek"), this may be accomplished by setting peek=true.

If a device token is used for authentication, The device ID is determined from the token, and the deviceId query parameter is ignored. If another form of authentication is used, the deviceId parameter must be provided.

Authorizations:

jwtapiKeyapiKeyAltdeviceToken

query Parameters

deviceId	string Device ID
peek	boolean Default: false A "peek" operation on the cloud event queue. If false (default), viewing the event will de-queue it, effectively "marking it as read." If true, the events returned will remain on the queue, and be returned again on the next request.
limit	integer <int32> [ 1 .. 10000 ] Default: 100 Example: limit=10 max records to return for pagination
page	integer <int32> >= 1 Default: 1 Example: page=5 desired page for pagination
elementName	string Element Name

Responses

Response samples

200
400
401
404

Content type

application/json

[ ]

Fetch the next queued cloud event for a device

Returns the next queued CloudEvent for the device. Returns 204 NO CONTENT if there are none.

CloudEvents are a queue of messages for a device. By default, they are dequeued when accessed. If you wish to access events in the queue without removing them from the queue (a "peek"), this may be accomplished by setting peek=true.

If a device token is used for authentication, The device ID is determined from the token, and the deviceId query parameter is ignored. If another form of authentication is used, the deviceId parameter must be provided.

Authorizations:

jwtapiKeyapiKeyAltdeviceToken

query Parameters

deviceId	string Device ID
peek	boolean Default: false A "peek" operation on the cloud event queue. If false (default), viewing the event will de-queue it, effectively "marking it as read." If true, the events returned will remain on the queue, and be returned again on the next request.
elementName	string Element Name

Responses

Response samples

200
400
401
404

Content type

application/json

true

Third-party Device Event integrations

Send an HTTP webhook to Atmosphere from your third-party IoT service.

Authorizations:

apiKeyapiKeyAlt

query Parameters

integration	string Enum: "custom" "ble" "lora" "sigfox" "zigbee" Specifies the type of integration between the third-party service and the Atmosphere IoT API. Executes all Device Event elements that have the integration type specified by the project found with the supplied `projectUuid` query parameter.
organizationId	string Example: organizationId=6205319c51ccf761dfb9a0be Specifies the organizationId of the organization to provision the device into. If the organizationId is not provided, the API will fall back to the user's organization that is resolved from providing the Authorization or api_auth_token headers. The organization must be accessible by the user initiating the integration request, devices cannot be provisioned in an organization above the user's.
eventsRef	string Examples: eventsRef=$.sensorMessages[] - JSONPath expression to "split" the request body as described in the provided example. The split entries are referred to as Event Blocks. eventsRef=sensorMessages - String can be used to refer to a top-level property of an object in the request body. JSONPath JavaScript evaluations are not allowed.* If this query parameter not provided, the entire request body is parsed by the API. String or JSONPath expression that will be used to break up the request body into an array, from which the `deviceTag` query parameter's values will be deduced. If not provided, the entire request body is treated as a single Device Event. Suppose the following request body needs to be split up into separate payloads of data under the `sensorMessages` array, such that multiple Device Events are parsed for distinct devices in one request. Notice how each entry contains a distinct `sensorID`: { "gatewayMessage": { "gatewayID": "10000", "gatewayName": "ExampleGateway", "accountID": "xxxx", "networkID": "xxxx", "messageType": "0", "power": "0", "batteryLevel": "101", "date": "6/18/2016 7:39:01 PM", "count": "3", "signalStrength": "29", "pendingChange": "False" }, "sensorMessages": [ { "sensorID": "10001", "sensorName": "Temp1", "applicationID": "6E2F41EC-C7CC-49D7-AE78-D28366412347", "networkID": "xxxx", "dataMessageGUID": "78642056-CBD8-43B0-9A4B-247E58D3B6CB", "state": "0", "messageDate": "6/18/2016 7:37:48 PM", "rawData": "23.7", "dataType": "TemperatureData", "dataValue": "23.7", "plotValues": "74.66", "plotLabels": "Fahrenheit", "batteryLevel": "100", "signalStrength": "100", "pendingChange": "False", "voltage": "3.24" }, { "sensorID": "99981", "sensorName": "Temp2", "applicationID": "766EA665-D121-433C-8AF7-014FA0A389EF", "networkID": "xxxx", "dataMessageGUID": "30041B9F-A8F4-404E-9FDC-48A83BA017A1", "state": "0", "messageDate": "6/19/2018 8:37:48 PM", "rawData": "62.4", "dataType": "TemperatureData", "dataValue": "62.4", "plotValues": "66.74", "plotLabels": "Fahrenheit", "batteryLevel": "78", "signalStrength": "22", "pendingChange": "True", "voltage": "3.48" } ] } In order to separate each event, a JSONPath expression of `$.sensorMessages[*]` can be passed to yield the following: [ { "sensorID": "10001", "sensorName": "Temp1", "applicationID": "2", "networkID": "xxxx", "dataMessageGUID": "78642056-CBD8-43B0-9A4B-247E58D3B6CB", "state": "0", "messageDate": "6/18/2016 7:37:48 PM", "rawData": "23.7", "dataType": "TemperatureData", "dataValue": "23.7", "plotValues": "74.66", "plotLabels": "Fahrenheit", "batteryLevel": "100", "signalStrength": "100", "pendingChange": "False", "voltage": "3.24" }, { "sensorID": "99981", "sensorName": "Temp2", "applicationID": "5", "networkID": "xxxx", "dataMessageGUID": "30041B9F-A8F4-404E-9FDC-48A83BA017A1", "state": "0", "messageDate": "6/19/2018 8:37:48 PM", "rawData": "62.4", "dataType": "TemperatureData", "dataValue": "62.4", "plotValues": "66.74", "plotLabels": "Fahrenheit", "batteryLevel": "78", "signalStrength": "22", "pendingChange": "True", "voltage": "3.48" } ] Once parsed with the `eventsRef` query parameter, the `deviceTagValueRef` and `projectUuidMapRef` parameters will operate on each element of this array. This will extract the individual `deviceTag` query parameter values to be assigned to the device(s) metadata fields. The array generated by `projectUuidMapRef` will be used to find values in the provided `projectUuidMap`. This will determine which devices will be provisioned to which `projectUuid` if auto-provisioning is necessary. The supplied `projectUuid` query parameter will specify the project that the device(s) will be provisioned against. If devices do not already exist with the metadata tag of the provided `deviceTag` query parameter, then they will be automatically provisioned under the organization of the user making the request.
deviceTag	string Example: deviceTag=fooId User-defined label for the values resolved by the `deviceTagValue` or `deviceTagValueRef` query parameters on on the device's metadata object like so: `{ deviceTag: deviceTagValue }` This is stored on the device metadata, then used to look up the device when the request is posted to the API. If the device is not found, it will be automatically provisioned with the `deviceTag` and `deviceTagValue` as described above.
deviceTagValue	string Example: deviceTagValue=sensorID Provides Atmosphere IoT the ID of the device on the third-party-integration service. Can be used directly to find the device in tandem with the `deviceTag`, or to assign it during the auto-provisioning process on Atmosphere IoT.
deviceTagValueRef	string Examples: deviceTagValueRef=$.sensorID - JSONPath expression to identify the values that that will be mapped to the `deviceTag` in the metadata of the device(s) from the payloads generated by `eventsRef`. deviceTagValueRef=sensorID - String to refer to a top-level property of an object in the `eventsRef` payloads. JSONPath JavaScript evaluations are not allowed. Means by which the API will find the individual values to be stored in the device metadata under the key specified by the `deviceTag` query parameter. A JSONPath Expression or string can be used to filter out the appropriate key in the body. If the `eventsRef` query parameter is provided, then this parameter will be used against the resolved data structure filtered from the request body by the `eventsRef` JSONPath expression.
extraMeta	object Example: foo1=bar1&foo2=bar2 Needs to be URI Encoded. JSON that stores additional metadata that will be assigned to the device when it auto-provisions itself on the Atmosphere IoT platform. Does not overwrite metadata that already exists on the device(s).
	object Nullable Example: Equipment ID=$.end_device_ids.device_id&loraDevEUI=$.end_device_ids.device_id Needs to be URI Encoded. JSON Mapping that allows the consumer to assign additional metadata fields to the device when a request is sent to the integration API. Each key in the mapping is a label for the key-value pair that will be added to the device's metadata. Each value is a JSONPath expression that matches fields in the body of the request sent to the API. The example provided will yield a custom metadata object that contains an Equipment ID and Lora Device EUI: { 'Equipment ID': '$.end_device_ids.device_id', 'loraDevEUI': '$.end_device_ids.device_id'} This parameter will not erase existing device metadata!
projectUuid	string Example: projectUuid=2bcb4d97-09b8-4f2f-a7e2-a92701477dcf The identifier for the Project that will be used when auto-provisioning the device. To determine how the Project will respond to Device Events sent over this endpoint, contact the Technicians and Administrators belonging to your Organization for more details if you do not have access to the Project.
projectUuidMap	object Example: 6E2F41EC-C7CC-49D7-AE78-D28366412347=62f0fd4c-b3d9-4453-baa5-7ccde5f58366&766EA665-D121-433C-8AF7-014FA0A389EF=39916f9a-e781-447c-afd6-930a8a359888 Needs to be URI Encoded. JSON Mapping where each key is a key in the data structure resolved from the `projectUuidMapRef` JSONPath evaluation. For example, the `projectUuidMapRef` query parameter looks at the `applicationID` field for each event by passing `$.applicationID`. The values for each `applicationID` are searched in the mapping. If a `projectUuid` is found, it will be used to provision the device if auto-provisioning is necessary.
projectUuidMapRef	string Example: projectUuidMapRef=$.applicationID JSONPath JavaScript evaluations are not allowed. JSONPath expression to extract values from the array generated by the `eventsRef` query parameter for the provided `projectUuidMap`. When a resolved value matches an entry in `projectUuidMap`, the matched `projectUuid` will be used to autoprovision the device if it has not been created yet.
	object Nullable Example: rawData=$.rawData&timestamp=$.messageDate Needs to be URI Encoded. JSON Mapping that allows the consumer to construct a custom object to be processed as a Device Event. Each key in the mapping corresponds to a key in the custom object. Each value is a JSONPath expression that matches fields in the Event Block that contains the payload. Event blocks are created by passing the eventsRef parameter. If not provided, the API assumes that one Event Block has been created. The example provided will yield a custom payload object as such for the first Event Block: { rawData: 23.7, timestamp: 6/18/2016 7:37:48 PM}
debug	string Example: debug=true When set to true, a 200 response is sent with information regarding the processing of the request from the third-party integration. Includes the data identified with the provided JSONPath expressions for the `eventsRef` and `deviceTagValueRef` query parameters that were passed, and if any devices were provisioned in the process.

header Parameters

integration	string Enum: "custom" "ble" "lora" "sigfox" "zigbee" Specifies the type of integration between the third-party service and the Atmosphere IoT API. Executes all Device Event elements that have the integration type specified by the project found with the supplied `projectUuid` header parameter.
organizationId	string Example: 6205319c51ccf761dfb9a0be Specifies the organizationId of the organization to provision the device into. If the organizationId is not provided, the API will fall back to the user's organization that is resolved from providing the Authorization or api_auth_token headers. The organization must be accessible by the user initiating the integration request, devices cannot be provisioned in an organization above the user's.
eventsRef	string Examples: $.sensorMessages[] - JSONPath expression to "split" the request body as described in the provided example. The split entries are referred to as Event Blocks. sensorMessages - String can be used to refer to a top-level property of an object in the request body. JSONPath JavaScript evaluations are not allowed.* If this header parameter not provided, the entire request body is parsed by the API. String or JSONPath expression that will be used to break up the request body into an array, from which the `deviceTag` header parameter's values will be deduced. If not provided, the entire request body is treated as a single Device Event. Suppose the following request body needs to be split up into separate payloads of data under the `sensorMessages` array, such that multiple Device Events are parsed for distinct devices in one request. Notice how each entry contains a distinct `sensorID`: { "gatewayMessage": { "gatewayID": "10000", "gatewayName": "ExampleGateway", "accountID": "xxxx", "networkID": "xxxx", "messageType": "0", "power": "0", "batteryLevel": "101", "date": "6/18/2016 7:39:01 PM", "count": "3", "signalStrength": "29", "pendingChange": "False" }, "sensorMessages": [ { "sensorID": "10001", "sensorName": "Temp1", "applicationID": "6E2F41EC-C7CC-49D7-AE78-D28366412347", "networkID": "xxxx", "dataMessageGUID": "78642056-CBD8-43B0-9A4B-247E58D3B6CB", "state": "0", "messageDate": "6/18/2016 7:37:48 PM", "rawData": "23.7", "dataType": "TemperatureData", "dataValue": "23.7", "plotValues": "74.66", "plotLabels": "Fahrenheit", "batteryLevel": "100", "signalStrength": "100", "pendingChange": "False", "voltage": "3.24" }, { "sensorID": "99981", "sensorName": "Temp2", "applicationID": "766EA665-D121-433C-8AF7-014FA0A389EF", "networkID": "xxxx", "dataMessageGUID": "30041B9F-A8F4-404E-9FDC-48A83BA017A1", "state": "0", "messageDate": "6/19/2018 8:37:48 PM", "rawData": "62.4", "dataType": "TemperatureData", "dataValue": "62.4", "plotValues": "66.74", "plotLabels": "Fahrenheit", "batteryLevel": "78", "signalStrength": "22", "pendingChange": "True", "voltage": "3.48" } ] } In order to separate each event, a JSONPath expression of `$.sensorMessages[*]` can be passed to yield the following: [ { "sensorID": "10001", "sensorName": "Temp1", "applicationID": "2", "networkID": "xxxx", "dataMessageGUID": "78642056-CBD8-43B0-9A4B-247E58D3B6CB", "state": "0", "messageDate": "6/18/2016 7:37:48 PM", "rawData": "23.7", "dataType": "TemperatureData", "dataValue": "23.7", "plotValues": "74.66", "plotLabels": "Fahrenheit", "batteryLevel": "100", "signalStrength": "100", "pendingChange": "False", "voltage": "3.24" }, { "sensorID": "99981", "sensorName": "Temp2", "applicationID": "5", "networkID": "xxxx", "dataMessageGUID": "30041B9F-A8F4-404E-9FDC-48A83BA017A1", "state": "0", "messageDate": "6/19/2018 8:37:48 PM", "rawData": "62.4", "dataType": "TemperatureData", "dataValue": "62.4", "plotValues": "66.74", "plotLabels": "Fahrenheit", "batteryLevel": "78", "signalStrength": "22", "pendingChange": "True", "voltage": "3.48" } ] Once parsed with the `eventsRef` header parameter, the `deviceTagValueRef` and `projectUuidMapRef` parameters will operate on each element of this array. This will extract the individual `deviceTag` header parameter values to be assigned to the device(s) metadata fields. The array generated by `projectUuidMapRef` will be used to find values in the provided `projectUuidMap`. This will determine which devices will be provisioned to which `projectUuid` if auto-provisioning is necessary. The supplied `projectUuid` header parameter will specify the project that the device(s) will be provisioned against. If devices do not already exist with the metadata tag of the provided `deviceTag` header parameter, then they will be automatically provisioned under the organization of the user making the request.
deviceTag	string Example: fooId User-defined label for the values resolved by the `deviceTagValue` or `deviceTagValueRef` header parameters on on the device's metadata object like so: `{ deviceTag: deviceTagValue }` This is stored on the device metadata, then used to look up the device when the request is posted to the API. If the device is not found, it will be automatically provisioned with the `deviceTag` and `deviceTagValue` as described above.
deviceTagValue	string Example: sensorID Provides Atmosphere IoT the ID of the device on the third-party-integration service. Can be used directly to find the device in tandem with the `deviceTag`, or to assign it during the auto-provisioning process on Atmosphere IoT.
deviceTagValueRef	string Examples: $.sensorID - JSONPath expression to identify the values that that will be mapped to the `deviceTag` in the metadata of the device(s) from the payloads generated by `eventsRef`. sensorID - String to refer to a top-level property of an object in the `eventsRef` payloads. JSONPath JavaScript evaluations are not allowed. Means by which the API will find the individual values to be stored in the device metadata under the key specified by the `deviceTag` header parameter. A JSONPath Expression or string can be used to filter out the appropriate key in the body. If the `eventsRef` header parameter is provided, then this parameter will be used against the resolved data structure filtered from the request body by the `eventsRef` JSONPath expression.
extraMeta	object Example: foo1,bar1,foo2,bar2 Needs to be URI Encoded. JSON that stores additional metadata that will be assigned to the device when it auto-provisions itself on the Atmosphere IoT platform. Does not overwrite metadata that already exists on the device(s).
	string or object Example: Equipment ID,$.end_device_ids.device_id,loraDevEUI,$.end_device_ids.device_id Needs to be URI Encoded. JSON Mapping that allows the consumer to assign additional metadata fields to the device when a request is sent to the integration API. Each key in the mapping is a label for the key-value pair that will be added to the device's metadata. Each value is a JSONPath expression that matches fields in the body of the request sent to the API. The example provided will yield a custom metadata object that contains an Equipment ID and Lora Device EUI: { 'Equipment ID': '$.end_device_ids.device_id', 'loraDevEUI': '$.end_device_ids.device_id'} This parameter will not erase existing device metadata!
projectUuid	string Example: 2bcb4d97-09b8-4f2f-a7e2-a92701477dcf The identifier for the Project that will be used when auto-provisioning the device. To determine how the Project will respond to Device Events sent over this endpoint, contact the Technicians and Administrators belonging to your Organization for more details if you do not have access to the Project.
projectUuidMap	object Example: 6E2F41EC-C7CC-49D7-AE78-D28366412347,62f0fd4c-b3d9-4453-baa5-7ccde5f58366,766EA665-D121-433C-8AF7-014FA0A389EF,39916f9a-e781-447c-afd6-930a8a359888 Needs to be URI Encoded. JSON Mapping where each key is a key in the data structure resolved from the `projectUuidMapRef` JSONPath evaluation. For example, the `projectUuidMapRef` header parameter looks at the `applicationID` field for each event by passing `$.applicationID`. The values for each `applicationID` are searched in the mapping. If a `projectUuid` is found, it will be used to provision the device if auto-provisioning is necessary.
projectUuidMapRef	string Example: $.applicationID JSONPath JavaScript evaluations are not allowed. JSONPath expression to extract values from the array generated by the `eventsRef` header parameter for the provided `projectUuidMap`. When a resolved value matches an entry in `projectUuidMap`, the matched `projectUuid` will be used to autoprovision the device if it has not been created yet.
	string or object Example: rawData,$.rawData,timestamp,$.messageDate Needs to be URI Encoded. JSON Mapping that allows the consumer to construct a custom object to be processed as a Device Event. Each key in the mapping corresponds to a key in the custom object. Each value is a JSONPath expression that matches fields in the Event Block that contains the payload. Event blocks are created by passing the eventsRef parameter. If not provided, the API assumes that one Event Block has been created. The example provided will yield a custom payload object as such for the first Event Block: { rawData: 23.7, timestamp: 6/18/2016 7:37:48 PM}
debug	string Example: true When set to true, a 200 response is sent with information regarding the processing of the request from the third-party integration. Includes the data identified with the provided JSONPath expressions for the `eventsRef` and `deviceTagValueRef` header parameters that were passed, and if any devices were provisioned in the process.

Request Body schema: application/json

Third-party event webhook / HTTP payload.

Any of

string Nullable

Responses

Request samples

Payload

Content type

application/json

{"gatewayMessage": {"gatewayID": "10000",
"gatewayName": "ExampleGateway",
"accountID": "xxxx",
"networkID": "xxxx",
"messageType": "0",
"power": "0",
"batteryLevel": "101",
"date": "6/18/2016 7:39:01 PM",
"count": "3",
"signalStrength": "29",
"pendingChange": "False"
},
"sensorMessages": [{"sensorID": "10001",
"sensorName": "Temp1",
"applicationID": "6E2F41EC-C7CC-49D7-AE78-D28366412347",
"networkID": "xxxx",
"dataMessageGUID": "78642056-CBD8-43B0-9A4B-247E58D3B6CB",
"state": "0",
"messageDate": "6/18/2016 7:37:48 PM",
"rawData": "23.7",
"dataType": "TemperatureData",
"dataValue": "23.7",
"plotValues": "74.66",
"plotLabels": "Fahrenheit",
"batteryLevel": "100",
"signalStrength": "100",
"pendingChange": "False",
"voltage": "3.24"
},
{"sensorID": "99981",
"sensorName": "Temp2",
"applicationID": "766EA665-D121-433C-8AF7-014FA0A389EF",
"networkID": "xxxx",
"dataMessageGUID": "30041B9F-A8F4-404E-9FDC-48A83BA017A1",
"state": "0",
"messageDate": "6/19/2018 8:37:48 PM",
"rawData": "62.4",
"dataType": "TemperatureData",
"dataValue": "62.4",
"plotValues": "66.74",
"plotLabels": "Fahrenheit",
"batteryLevel": "78",
"signalStrength": "22",
"pendingChange": "True",
"voltage": "3.48"
}
]
}

Response samples

200
400
401

Content type

application/json

{"debug": {"errors": [{"message": "Device validation failed: projectUuid: Path `projectUuid` is required."
}
],
"extractedTasks": {"requestBody": {"gatewayMessage": {"gatewayID": "10000",
"gatewayName": "ExampleGateway",
"accountID": "xxxx",
"networkID": "xxxx",
"messageType": "0",
"power": "0",
"batteryLevel": "101",
"date": "6/18/2016 7:39:01 PM",
"count": "3",
"signalStrength": "29",
"pendingChange": "False"
},
"sensorMessages": [{"sensorID": "10001",
"sensorName": "Temp1",
"applicationID": "2",
"networkID": "xxxx",
"dataMessageGUID": "78642056-CBD8-43B0-9A4B-247E58D3B6CB",
"state": "0",
"messageDate": "6/18/2016 7:37:48 PM",
"rawData": "23.7",
"dataType": "TemperatureData",
"dataValue": "23.7",
"plotValues": "74.66",
"plotLabels": "Fahrenheit",
"batteryLevel": "100",
"signalStrength": "100",
"pendingChange": "False",
"voltage": "3.24"
},
{"sensorID": "99981",
"sensorName": "Sonic2",
"applicationID": "67",
"networkID": "xxxx",
"dataMessageGUID": "30041B9F-A8F4-404E-9FDC-48A83BA017A1",
"state": "0",
"messageDate": "6/19/2018 8:37:48 PM",
"rawData": "62.4",
"dataType": "SonicData",
"dataValue": "62.4",
"plotValues": "66.74",
"plotLabels": "SonicUnits",
"batteryLevel": "78",
"signalStrength": "22",
"pendingChange": "True",
"voltage": "3.48"
}
]
},
"tasks": [{"deviceTag": "iMonnitID",
"extraMeta": {"serialNumber": "123456789",
"state": "READY"
},
"integration": "custom",
"payloads": [{"gatewayMessage": {"gatewayID": "10000",
"gatewayName": "ExampleGateway",
"accountID": "xxxx",
"networkID": "xxxx",
"messageType": "0",
"power": "0",
"batteryLevel": "101",
"date": "6/18/2016 7:39:01 PM",
"count": "3",
"signalStrength": "29",
"pendingChange": "False"
},
"sensorMessages": [{"sensorID": "10001",
"sensorName": "Temp1",
"applicationID": "2",
"networkID": "xxxx",
"dataMessageGUID": "78642056-CBD8-43B0-9A4B-247E58D3B6CB",
"state": "0",
"messageDate": "6/18/2016 7:37:48 PM",
"rawData": "23.7",
"dataType": "TemperatureData",
"dataValue": "23.7",
"plotValues": "74.66",
"plotLabels": "Fahrenheit",
"batteryLevel": "100",
"signalStrength": "100",
"pendingChange": "False",
"voltage": "3.24"
},
{"sensorID": "99981",
"sensorName": "Sonic2",
"applicationID": "67",
"networkID": "xxxx",
"dataMessageGUID": "30041B9F-A8F4-404E-9FDC-48A83BA017A1",
"state": "0",
"messageDate": "6/19/2018 8:37:48 PM",
"rawData": "62.4",
"dataType": "SonicData",
"dataValue": "62.4",
"plotValues": "66.74",
"plotLabels": "SonicUnits",
"batteryLevel": "78",
"signalStrength": "22",
"pendingChange": "True",
"voltage": "3.48"
}
]
}
],
"organization": "60f9d662f0f3ca6e8a39bd76",
"owner": "Abdul.Kareem00221",
"deviceTagValue": "IoTServiceId",
"projectUuid": "c6717835-4adf-493e-b7ba-ec6616c0a43d"
}
],
"errors": [{"message": "Device validation failed: projectUuid: Path `projectUuid` is required."
}
]
},
"taskExecutions": {"processed": [{"errors": [{"message": "Device validation failed: projectUuid: Path `projectUuid` is required."
}
],
"devicesProvisioned": [{"deviceId": "60f9d664f0f3ca6e8a39bdd3",
"name": "IoTServiceId 1112234455",
"organizationId": "60f9d662f0f3ca6e8a39bd76",
"projectUuid": "c6717835-4adf-493e-b7ba-ec6616c0a43d",
"deviceTag": "IoTServiceId",
"deviceTagValue": "1112234455"
}
],
"eventsProcessed": [{"_id": "60f9d664f0f3ca6e8a39bdd6",
"receivedAt": "2021-07-22T20:34:44.878Z",
"integration": "custom",
"deviceId": "60f9d664f0f3ca6e8a39bdd3",
"payload": {"gatewayMessage": {"gatewayID": "10000",
"gatewayName": "ExampleGateway",
"accountID": "xxxx",
"networkID": "xxxx",
"messageType": "0",
"power": "0",
"batteryLevel": "101",
"date": "6/18/2016 7:39:01 PM",
"count": "3",
"signalStrength": "29",
"pendingChange": "False"
},
"sensorMessages": [{"sensorID": "10001",
"sensorName": "Temp1",
"applicationID": "2",
"networkID": "xxxx",
"dataMessageGUID": "78642056-CBD8-43B0-9A4B-247E58D3B6CB",
"state": "0",
"messageDate": "6/18/2016 7:37:48 PM",
"rawData": "23.7",
"dataType": "TemperatureData",
"dataValue": "23.7",
"plotValues": "74.66",
"plotLabels": "Fahrenheit",
"batteryLevel": "100",
"signalStrength": "100",
"pendingChange": "False",
"voltage": "3.24"
},
{"sensorID": "99981",
"sensorName": "Sonic2",
"applicationID": "67",
"networkID": "xxxx",
"dataMessageGUID": "30041B9F-A8F4-404E-9FDC-48A83BA017A1",
"state": "0",
"messageDate": "6/19/2018 8:37:48 PM",
"rawData": "62.4",
"dataType": "SonicData",
"dataValue": "62.4",
"plotValues": "66.74",
"plotLabels": "SonicUnits",
"batteryLevel": "78",
"signalStrength": "22",
"pendingChange": "True",
"voltage": "3.48"
}
]
}
}
]
}
],
"errors": [{"message": "Device validation failed: projectUuid: Path `projectUuid` is required."
}
]
}
}
}

organizations

Operations concerning organizations

Fetch all organizations

Fetches organizations according to the parameters given.

Supported sort fields:

name (default)
description
createdAt
updatedAt

Authorizations:

jwtapiKeyapiKeyAlt

query Parameters

	string or integer Default: 1 Maximum depth of the tree to return results. Default is 1. "all" will return all results.
limit	integer <int32> [ 1 .. 10000 ] Default: 100 Example: limit=10 max records to return for pagination
page	integer <int32> >= 1 Default: 1 Example: page=5 desired page for pagination
parentId	string parent organization id
searchText	string Example: searchText=SearchString Filters the results according to entries that match the supplied text. The specific fields searched vary according to the entity.
sortBy	Array of strings Example: sortBy=field1&sortBy=-field2 Sort the results according to this value. Allowed sort fields varies according to the entity. Optionally, the sort order may be specified by prepending a `+` for ascending and `-` for descending. This parameter may be specified multiple times, which will be processed in subsequent order (i.e. first supplied parameter will be primary sort, second supplied parameter will be secondary sort, etc).

Responses

Response samples

200
401

Content type

application/json

{"meta": {"totalDocs": 0,
"page": 0,
"limit": 0,
"hasPrevPage": true,
"hasNextPage": true,
"totalPages": 0
},
"data": [{"id": "string",
"name": "string",
"parentId": "string",
"description": "string",
"path": [{"name": "string",
"id": "string"
}
],
"imageUrl": "/v2/organizations/{id}/image.png",
"parentName": "string",
"createdAt": "string",
"updatedAt": "string",
"hasChildren": true,
"statusText": "none",
"statusInt": 6,
"deviceCount": 0,
"dataUsageMb": 0,
"deviceCountLimit": 0,
"dataUsageMbLimit": 0,
"childrenInheritDashboard": false,
"deviceTable": { }
}
]
}

Create a new organization

Creates new organization, returns the organization

Authorizations:

jwtapiKeyapiKeyAlt

Request Body schema: application/json

name required	string [ 1 .. 80 ] characters
parentId	string [ 0 .. 36 ] characters Nullable
description	string [ 0 .. 200 ] characters
childrenInheritDashboard	boolean Default: false
deviceTable	object Contains configuration related to the device table columns
property name*	any

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"parentId": "string",
"description": "string",
"childrenInheritDashboard": false,
"deviceTable": { }
}

Response samples

201
400
401

Content type

application/json

{"id": "string",
"name": "string",
"parentId": "string",
"description": "string",
"path": [{"name": "string",
"id": "string"
}
],
"imageUrl": "/v2/organizations/{id}/image.png",
"parentName": "string",
"createdAt": "string",
"updatedAt": "string",
"hasChildren": true,
"statusText": "none",
"statusInt": 6,
"deviceCount": 0,
"dataUsageMb": 0,
"deviceCountLimit": 0,
"dataUsageMbLimit": 0,
"childrenInheritDashboard": false,
"deviceTable": { }
}

Fetch an organization

Returns the organization with the specified ID.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Responses

Response samples

200
401
404

Content type

application/json

{"id": "string",
"name": "string",
"parentId": "string",
"description": "string",
"path": [{"name": "string",
"id": "string"
}
],
"imageUrl": "/v2/organizations/{id}/image.png",
"parentName": "string",
"createdAt": "string",
"updatedAt": "string",
"hasChildren": true,
"statusText": "none",
"statusInt": 6,
"deviceCount": 0,
"dataUsageMb": 0,
"deviceCountLimit": 0,
"dataUsageMbLimit": 0,
"childrenInheritDashboard": false,
"deviceTable": { }
}

Update an organization

Updates the organization with the specified ID and returns the updated version.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Request Body schema: application/json

name required	string [ 1 .. 80 ] characters
parentId	string [ 0 .. 36 ] characters Nullable
description	string [ 0 .. 200 ] characters
childrenInheritDashboard	boolean Default: false
deviceTable	object Contains configuration related to the device table columns
property name*	any

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"parentId": "string",
"description": "string",
"childrenInheritDashboard": false,
"deviceTable": { }
}

Response samples

200
401
404

Content type

application/json

{"id": "string",
"name": "string",
"parentId": "string",
"description": "string",
"path": [{"name": "string",
"id": "string"
}
],
"imageUrl": "/v2/organizations/{id}/image.png",
"parentName": "string",
"createdAt": "string",
"updatedAt": "string",
"hasChildren": true,
"statusText": "none",
"statusInt": 6,
"deviceCount": 0,
"dataUsageMb": 0,
"deviceCountLimit": 0,
"dataUsageMbLimit": 0,
"childrenInheritDashboard": false,
"deviceTable": { }
}

Delete an organization

Deletes the organization with the specified ID.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Responses

Response samples

401
404

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

Fetch an organization's branding.

Returns the organization branding.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Responses

Response samples

200
404

Content type

application/json

{"organizationId": "stringstringstringstring",
"companyName": "string",
"addressLine1": "string",
"addressLine2": "string",
"domain": "string",
"domainHTTPFileOverrides": { },
"domainPublicConfiguration": { },
"email": "user@example.com",
"emailSenderName": "string"
}

Update an Organization's branding

Updates the organization branding for the specified organization ID and returns the branding information.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Request Body schema: application/json

organizationId	string [ 24 .. 36 ] characters The Organization to which this branding belongs.
companyName	string
addressLine1	string
addressLine2	string
domain	string The FQDN associated with the organization and it's branding data.
domainHTTPFileOverrides	object
domainPublicConfiguration	object
email	string <email>
emailSenderName	string The name associated with the email such as Foo Bar foo.bar@example.com

Responses

Request samples

Payload

Content type

application/json

{"organizationId": "stringstringstringstring",
"companyName": "string",
"addressLine1": "string",
"addressLine2": "string",
"domain": "string",
"domainHTTPFileOverrides": { },
"domainPublicConfiguration": { },
"email": "user@example.com",
"emailSenderName": "string"
}

Response samples

200
401
404

Content type

application/json

{"organizationId": "stringstringstringstring",
"companyName": "string",
"addressLine1": "string",
"addressLine2": "string",
"domain": "string",
"domainHTTPFileOverrides": { },
"domainPublicConfiguration": { },
"email": "user@example.com",
"emailSenderName": "string"
}

Clear an Organization's branding

Clears the organization dashboard for the specified organization ID.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Responses

Response samples

401
404

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

Fetch an organization's image

Returns the organization image

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Responses

Response samples

401
404

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

Update a Organization's image

Updates the image for the specified ID.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Request Body schema: text/plain

string (Image) ^data:image\/(png|jpg|jpeg|gif|svg|webp);base...

Responses

Response samples

401
404

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

Delete an Organization's set image

Deletes the image set set for the specified ID.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Responses

Response samples

401
404

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

Fetch an organization's dashboard

Returns the organization dashboard

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Responses

Response samples

200
404

Content type

application/json

{"name": "string",
"options": { },
"configuration": { }
}

Update an Organization's dashboard

Updates the organization dashboard for the specified organization ID and returns the dashboard.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Request Body schema: application/json

name	string
options	object
configuration required	object

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"options": { },
"configuration": { }
}

Response samples

200
401
404

Content type

application/json

{"name": "string",
"options": { },
"configuration": { }
}

Delete an Organization's dashboard

Deletes the organization dashboard for the specified organization ID.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Responses

Response samples

401
404

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

Fetch an organization's device table configurations

Returns the organization device table configurations

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Responses

Response samples

200
404

Content type

application/json

{"organizationId": "stringstringstringstring",
"deviceId": "string",
"columns": [{"path": "string",
"type": "DeviceModel"
}
]
}

Update an Organization's device table configurations

Updates the organization device table configurations for the specified organization ID and returns them.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Request Body schema: application/json

organizationId required	string [ 24 .. 36 ] characters
deviceId	string
required	Array of objects (DeviceTableColumn)

Responses

Request samples

Payload

Content type

application/json

{"organizationId": "stringstringstringstring",
"deviceId": "string",
"columns": [{"path": "string",
"type": "DeviceModel"
}
]
}

Response samples

200
401
404

Content type

application/json

{"organizationId": "stringstringstringstring",
"deviceId": "string",
"columns": [{"path": "string",
"type": "DeviceModel"
}
]
}

Delete an Organization's device table configurations

Deletes the device table configurations for the organization by ID.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Responses

Response samples

401
404

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

Fetch an an organization, while also returning the organization's total data usage and device usage on the platform.

Returns the organization usage data. Also includes the data usage of the organizations underneath.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Responses

Response samples

200
404

Content type

application/json

{"id": "string",
"name": "string",
"parentId": "string",
"description": "string",
"path": [{"name": "string",
"id": "string"
}
],
"imageUrl": "/v2/organizations/{id}/image.png",
"parentName": "string",
"createdAt": "string",
"updatedAt": "string",
"hasChildren": true,
"statusText": "none",
"statusInt": 6,
"deviceCount": 0,
"dataUsageMb": 0,
"deviceCountLimit": 0,
"dataUsageMbLimit": 0,
"childrenInheritDashboard": false,
"deviceTable": { }
}

projects

A Project embodies your application functionality on the platform. It contains the logic for processing data from your device, and optionally logic for the device itself (i.e. firmware) and/or a user interface that can be utilized on the web or in the mobile app.

Fetches projects according to the parameters given.

Supported sort fields:

name (default)
createdAt
updatedAt

Authorizations:

jwtapiKeyapiKeyAlt

query Parameters

	string or integer Default: 1 Maximum depth of the tree to return results. Default is 1. "all" will return all results.
page	integer <int32> >= 1 Default: 1 Example: page=5 desired page for pagination
limit	integer <int32> [ 1 .. 10000 ] Default: 100 Example: limit=10 max records to return for pagination
organizationId	string organization ID query
searchText	string Example: searchText=SearchString Filters the results according to entries that match the supplied text. The specific fields searched vary according to the entity.
sortBy	Array of strings Example: sortBy=field1&sortBy=-field2 Sort the results according to this value. Allowed sort fields varies according to the entity. Optionally, the sort order may be specified by prepending a `+` for ascending and `-` for descending. This parameter may be specified multiple times, which will be processed in subsequent order (i.e. first supplied parameter will be primary sort, second supplied parameter will be secondary sort, etc).
	object Example: filter[type]=esp32 Filters the results according to entries that match the supplied filter.

Responses

Response samples

200
401

Content type

application/json

{"meta": {"totalDocs": 0,
"page": 0,
"limit": 0,
"hasPrevPage": true,
"hasNextPage": true,
"totalPages": 0
},
"data": [{"id": "string",
"name": "string",
"type": "string",
"uuid": "string",
"organizationId": "stringstringstringstring",
"organizationName": "string",
"imageUrl": "https://foo.bar/path/to/image.png",
"createdBy": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}

Create a new project

Create a new project, responds with the newly created project

Authorizations:

jwtapiKeyapiKeyAlt

Request Body schema: application/json

name required	string [ 1 .. 80 ] characters
organizationId	string [ 24 .. 36 ] characters

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"organizationId": "stringstringstringstring"
}

Response samples

201
400
401

Content type

application/json

{"id": "string",
"name": "string",
"type": "string",
"uuid": "string",
"organizationId": "stringstringstringstring",
"organizationName": "string",
"imageUrl": "https://foo.bar/path/to/image.png",
"createdBy": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Fetch a project by it's ID or UUID.

Returns the project with the specified Project ID or Project UUID.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Responses

Response samples

200
401
404

Content type

application/json

{"id": "string",
"name": "string",
"type": "string",
"uuid": "string",
"organizationId": "stringstringstringstring",
"organizationName": "string",
"imageUrl": "https://foo.bar/path/to/image.png",
"createdBy": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Update an existing project

Updates the project with the specified ID and returns the updated version.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Request Body schema: application/json

name required	string [ 1 .. 80 ] characters
organizationId	string [ 24 .. 36 ] characters

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"organizationId": "stringstringstringstring"
}

Response samples

200
401
404

Content type

application/json

{"id": "string",
"name": "string",
"type": "string",
"uuid": "string",
"organizationId": "stringstringstringstring",
"organizationName": "string",
"imageUrl": "https://foo.bar/path/to/image.png",
"createdBy": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Delete a project

Deletes the project with the specified ID.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Responses

Response samples

401
404

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

Fetch the specification for a project by either Project ID or Project UUID.

Returns the project specification (design) having the specified ID. A Project UUID may also be specified in place of the Project ID.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Responses

Response samples

200
401
404

Content type

application/json

{"name": "string",
"createVersion": "2",
"description": "",
"created": "2019-08-24T14:15:22Z",
"lastModified": "2019-08-24T14:15:22Z",
"meta": { },
"planes": { }
}

Set the specification for a project

Overwrites the current project specification (design) with the specified ID and returns the updated version.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Request Body schema: application/json

name required	string [ 1 .. 80 ] characters
createVersion	string [ 1 .. 16 ] characters Default: "2"
description	string [ 0 .. 2000 ] characters Default: ""
created	string <date-time>
lastModified	string <date-time>
meta	object Default: {}
planes	object Default: {}

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"createVersion": "2",
"description": "",
"created": "2019-08-24T14:15:22Z",
"lastModified": "2019-08-24T14:15:22Z",
"meta": { },
"planes": { }
}

Response samples

201
401
404

Content type

application/json

{"name": "string",
"createVersion": "2",
"description": "",
"created": "2019-08-24T14:15:22Z",
"lastModified": "2019-08-24T14:15:22Z",
"meta": { },
"planes": { }
}

Fetch a project's image

Returns the project image

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Responses

Response samples

401
404

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

Update a project's image

Updates the image for the specified ID.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Request Body schema: text/plain

string (Image) ^data:image\/(png|jpg|jpeg|gif|svg|webp);base...

Responses

Response samples

401
404

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

storage

Your project design can use Storage Elements to persist information that your project needs. Each such Storage Element effectively represents its own time-series database. Data stored in a Storage Element is accessed via the data API, and the database itself may be managed through the storage API.

The storage API provides operations such as checking the size of a Storage Element, and clearing out its data. Storage Elements are created automatically, according to your project design.

Fetches descriptions of storage elements for a device

Fetches devices according to the parameters given.

Supported sort fields:

name (default)

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

query Parameters

page	integer <int32> >= 1 Default: 1 Example: page=5 desired page for pagination
limit	integer <int32> [ 1 .. 10000 ] Default: 100 Example: limit=10 max records to return for pagination

Responses

Response samples

200
400
401
404

Content type

application/json

{"meta": {"totalDocs": 0,
"page": 0,
"limit": 0,
"hasPrevPage": true,
"hasNextPage": true,
"totalPages": 0
},
"bytesStored": 1024,
"storageElements": [{"name": "string",
"deviceId": "stringstringstringstring",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}

Delete all storage elements for a device.

Delete all storage elements for a device. This operation is permanent and cannot be undone.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Responses

Response samples

400
401
404

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

Fetches the description of a particular storage element for a device

Fetches devices according to the parameters given.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id required	string Resource ID
elementName required	string The name of an element

Responses

Response samples

200
401
404

Content type

application/json

{"name": "string",
"deviceId": "stringstringstringstring",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Delete a storage element for a device, by element name.

Delete a storage element for a device, by element name. This operation is permanent and cannot be undone.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id required	string Resource ID
elementName required	string The name of an element

Responses

Response samples

400
401
404

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

users

Operations concerning users

Delete a project's image

Deletes the image set set for the specified ID.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Responses

Response samples

401
404

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

Fetch all users

Fetches users according to the parameters given.

Supported sort fields:

username (default)
email
role
firstName
lastName
company
createdAt
updatedAt
lastActive

Authorizations:

jwtapiKeyapiKeyAlt

query Parameters

	string or integer Default: 1 Maximum depth of the tree to return results. Default is 1. "all" will return all results.
page	integer <int32> >= 1 Default: 1 Example: page=5 desired page for pagination
limit	integer <int32> [ 1 .. 10000 ] Default: 100 Example: limit=10 max records to return for pagination
organizationId	string organization ID query
searchText	string Example: searchText=SearchString Filters the results according to entries that match the supplied text. The specific fields searched vary according to the entity.
sortBy	Array of strings Example: sortBy=field1&sortBy=-field2 Sort the results according to this value. Allowed sort fields varies according to the entity. Optionally, the sort order may be specified by prepending a `+` for ascending and `-` for descending. This parameter may be specified multiple times, which will be processed in subsequent order (i.e. first supplied parameter will be primary sort, second supplied parameter will be secondary sort, etc).

Responses

Response samples

200
401

Content type

application/json

{"meta": {"totalDocs": 0,
"page": 0,
"limit": 0,
"hasPrevPage": true,
"hasNextPage": true,
"totalPages": 0
},
"data": [{"id": "string",
"username": "string",
"email": "user@example.com",
"role": "technican",
"tosHash": "string",
"firstName": "string",
"lastName": "string",
"company": "string",
"jobTitle": "string",
"language": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"lastActive": "2019-08-24T14:15:22Z",
"preferences": {"notifications": {"accountNotifications": {"inapp": true,
"email": false
},
"systemNotification": {"inapp": true,
"email": false
},
"deviceNotification": {"inapp": true,
"email": false
}
}
},
"imageUrl": "/users/{id}/image.png",
"organizationName": "string",
"organizationId": "string",
"disabled": true
}
]
}

Create a new user

Creates a new user.

Authorizations:

jwtapiKeyapiKeyAlt

Request Body schema: application/json

username required	string Username for the user. Must be globally unique. May be same as email.
password	string User's plaintext password. Only used for user creation.
passwordConfirmation	string User's plaintext password. Only used for user creation. Must match password field.
firstName required	string User's given name.
lastName required	string User's surname.
email required	string <email> Email address for the user. Must be globally unique.
company required	string Company name for the user.
role required	string The user's role.
organizationId	string
tosHash	string
language	string

Responses

Request samples

Payload

Content type

application/json

{"username": "string",
"password": "string",
"passwordConfirmation": "string",
"firstName": "string",
"lastName": "string",
"email": "user@example.com",
"company": "string",
"role": "developer",
"organizationId": "string",
"tosHash": "string",
"language": "string"
}

Response samples

201
400
401

Content type

application/json

{"id": "string",
"username": "string",
"email": "user@example.com",
"role": "technican",
"tosHash": "string",
"firstName": "string",
"lastName": "string",
"company": "string",
"jobTitle": "string",
"language": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"lastActive": "2019-08-24T14:15:22Z",
"preferences": {"notifications": {"accountNotifications": {"inapp": true,
"email": false
},
"systemNotification": {"inapp": true,
"email": false
},
"deviceNotification": {"inapp": true,
"email": false
}
}
},
"imageUrl": "/users/{id}/image.png",
"organizationName": "string",
"organizationId": "string",
"disabled": true
}

Fetch a user

Returns the user with the specified ID.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Responses

Response samples

200
401
404

Content type

application/json

{"id": "string",
"username": "string",
"email": "user@example.com",
"role": "technican",
"tosHash": "string",
"firstName": "string",
"lastName": "string",
"company": "string",
"jobTitle": "string",
"language": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"lastActive": "2019-08-24T14:15:22Z",
"preferences": {"notifications": {"accountNotifications": {"inapp": true,
"email": false
},
"systemNotification": {"inapp": true,
"email": false
},
"deviceNotification": {"inapp": true,
"email": false
}
}
},
"imageUrl": "/users/{id}/image.png",
"organizationName": "string",
"organizationId": "string",
"disabled": true
}

Update a user

Updates the user with the specified ID and returns the updated version.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Request Body schema: application/json

username required	string [ 1 .. 254 ] characters Username must be globally unique. Once the user is created, this field is read-only.
email required	string <email> [ 3 .. 254 ] characters Email must be globally unique. Once the user is created, this field is read-only.
role required	string Enum: "basicUser" "technician" "manager" "administrator" "developer" "systemAdmin" The user's role. When setting/changing a user's role, the user making the change may only set a role to which they have access.
password	string [ 6 .. 20 ] characters User's plaintext password. Only used when setting a new password.
passwordConfirmation	string [ 6 .. 20 ] characters User's plaintext password. Only used when setting a new password. Must match password field for successful save.
tosHash	string Hash used as a signature that the user has signed the Terms of Service. Only used when agreeing to terms of service.
firstName required	string [ 1 .. 80 ] characters
lastName required	string [ 1 .. 80 ] characters
company required	string [ 1 .. 80 ] characters
jobTitle	string [ 0 .. 80 ] characters
language	string [ 0 .. 80 ] characters
	object The user's preferences.
organizationName	string
organizationId	string The Organization to which this user belongs. If not set on a new user, it will be set to the same Organization as the user making the request.
reason	string [ 1 .. 300 ] characters Internal use only.
disabled	boolean Default: true Determines if the user is disabled or not

Responses

Request samples

Payload

Content type

application/json

{"username": "string",
"email": "user@example.com",
"role": "technican",
"password": "string",
"passwordConfirmation": "string",
"tosHash": "string",
"firstName": "string",
"lastName": "string",
"company": "string",
"jobTitle": "string",
"language": "string",
"preferences": {"notifications": {"accountNotifications": {"inapp": true,
"email": false
},
"systemNotification": {"inapp": true,
"email": false
},
"deviceNotification": {"inapp": true,
"email": false
}
}
},
"organizationName": "string",
"organizationId": "string",
"reason": "string",
"disabled": true
}

Response samples

200
401
404

Content type

application/json

{"id": "string",
"username": "string",
"email": "user@example.com",
"role": "technican",
"tosHash": "string",
"firstName": "string",
"lastName": "string",
"company": "string",
"jobTitle": "string",
"language": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"lastActive": "2019-08-24T14:15:22Z",
"preferences": {"notifications": {"accountNotifications": {"inapp": true,
"email": false
},
"systemNotification": {"inapp": true,
"email": false
},
"deviceNotification": {"inapp": true,
"email": false
}
}
},
"imageUrl": "/users/{id}/image.png",
"organizationName": "string",
"organizationId": "string",
"disabled": true
}

Delete a user

Deletes the user with the specified ID.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Responses

Response samples

401
404

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

Fetch a user's image

Returns the user image

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Responses

Response samples

401
404

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

Update a users image

Updates the image for the specified ID.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Request Body schema: text/plain

string (Image) ^data:image\/(png|jpg|jpeg|gif|svg|webp);base...

Responses

Response samples

401
404

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

Delete a user's set image

Deletes the image set set for the specified ID.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Responses

Response samples

401
404

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

notifications

Operations concerning notifications

Fetches notifications according to the parameters given.

Authorizations:

jwtapiKeyapiKeyAlt

query Parameters

page	integer <int32> >= 1 Default: 1 Example: page=5 desired page for pagination
limit	integer <int32> [ 1 .. 10000 ] Default: 100 Example: limit=10 max records to return for pagination
unread	boolean Show only unread notifications

Responses

Response samples

200
401

Content type

application/json

{"meta": {"totalDocs": 0,
"page": 0,
"limit": 0,
"hasPrevPage": true,
"hasNextPage": true,
"totalPages": 0
},
"data": [{"createdAt": "2020-10-16T14:33:10.345Z",
"id": "34958232845",
"type": "deviceNotification",
"read": false,
"translations": {"en-US": {"message": "Here is my message text"
},
"fr-FR": {"message": "voici mon texte de message"
}
}
}
]
}

Emit system-wide notification.

Emits a system notification, which every user on the platform will get.

Authorizations:

jwtapiKeyapiKeyAlt

Request Body schema: application/json

message

string non-empty

Responses

Request samples

Payload

Content type

application/json

{"message": "Here is my message text"
}

Response samples

400
401

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

Update all notifications

Updates all notifications

Authorizations:

jwtapiKeyapiKeyAlt

query Parameters

from	string <date-time> Example: from=2020-05-11T15:51:06Z Start date of resources. Inclusive.
to required	string <date-time> End date of resources

Request Body schema: application/json

read

boolean

Responses

Request samples

Payload

Content type

application/json

{"read": true
}

Response samples

401
404

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

Delete all notifications

Deletes all notifications

Authorizations:

jwtapiKeyapiKeyAlt

query Parameters

from	string <date-time> Example: from=2020-05-11T15:51:06Z Start date of resources. Inclusive.
to required	string <date-time> End date of resources

Responses

Response samples

401
404

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

Fetch a single notification

Returns the notification with the specified ID.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Responses

Response samples

200
401
404

Content type

application/json

{"createdAt": "2020-10-16T14:33:10.345Z",
"id": "34958232845",
"type": "deviceNotification",
"read": false,
"translations": {"en-US": {"message": "Here is my message text"
},
"fr-FR": {"message": "voici mon texte de message"
}
}
}

Update a notification

Updates the notification with the specified ID

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Request Body schema: application/json

read

boolean

Responses

Request samples

Payload

Content type

application/json

{"read": true
}

Response samples

401
404

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}

Delete a notification

Deletes the notification with the specified ID.

Authorizations:

jwtapiKeyapiKeyAlt

path Parameters

id

required

string

Resource ID

Responses

Response samples

401
404

Content type

application/json

{"message": "string",
"errors": [{"field": "string",
"message": "string"
}
]
}