Download OpenAPI specification:Download
API Specification of OSRAM Lightelligence
Get basic realm info. This includes the public key, which can be used to ensure a JWT was correctly signed by this idp (identity provider). The provided public_key is not PEM encoded, so for JWT verification it still needs PEM padding. To verify any issued JWT the key can be padded like:
-----BEGIN PUBLIC KEY-----
{{ACTUAL KEY}}
-----END PUBLIC KEY-----Success
Internal Server Error response
OAuth2 Production Environment
This is the URL endpoint for the Authorization Code Flow to get a temporary code to later exchange for a token. Use this code with the /token endpoint to get a user token.
Userinfo: provide optional scopes email profile to include more user information in authentication session.
Next step is to exchange the authorization code for a token at GET /protocol/openid-connect/token
| client_id required | string The ID of the OAuth2 client |
| redirect_uri required | string <uri> Valid redirect uri for the current client |
| scope required | string Space delimited list of scopes. When requesting an access token the scope |
| response_type required | string Value: "code" Response type for auth grant flow |
| response_mode required | string Enum: "form_post" "query" "fragment" Define how the response should be returned |
| nonce | string Required if using "response_mode=form_post" |
Success, callback to redirect_uri
Bad Request response.
Internal Server Error response
OAuth2 Production Environment
Openid endpoint to get an access token. Based on the grant_type different flows work here.
When using refresh_token as grant_type the new returned access token will be scoped with the same tenant as the previous one. Optionally the header tenant can be used to obtain a new access token for the user with a different tenant. This may not always work (the user might not be part of the tenant, the application might not be installed to the tenant or other reasons can forbid this operation).
Tip: Get user information by exchanging the token for userinfo at GET /protocol/openid-connect/userinfo
| tenant | string <uuid> Set the |
| client_id required | string The ID of the OAuth2 client |
| client_secret | string Secret to use with your clientId. (Not required if using 'public' client) |
| grant_type required | string Enum: "authorization_code" "client_credentials" "id_token" "refresh_token" OAuth2 grant types supported by OLT |
| redirect_uri | string <uri> Valid redirect uri for the current client |
| code | string The Authorization Code if using Authorization Code Flow |
| scope | string Space delimited list of scopes. When requesting an access token the scope |
Success
Bad Request response.
Internal Server Error response
OAuth2 Production Environment
The UserInfo endpoint is an OAuth 2.0 protected resource where client applications can retrieve consented claims, or assertions, about the logged in end-user. This is retrieved by using a valid access_token for the OLT platform through the Authorization header.
Success
Bad Request response.
Unauthorized response.
Internal Server Error response
OAuth2 Production Environment
Notifications are created and configured by users. They use filters to process events and then trigger a notification that is sent to a specific channel (i.e. email) depending on its configuration.
Retrieves a list of notifications containing filter information as well as notification template.
By default the list is sorted by creation datetime in descending order. So, most recently created entry goes first.
| page | integer >= 0 Default: 0 The number of the result page starting with 0. |
| pageSize | integer [ 1 .. 100 ] Default: 20 The number of result per page. |
Success - A notifications list.
Bad request
Authentication required
Action is forbidden
Internal Server Error
Production Environment
Request a new notification to be created.
| notificationTemplate required | object Notification template |
| notificationFilter required | object Filter which allows to receive notifications for specific events; The filter conditions ("deviceEvent", "deviceId", "deviceTag", etc) are treated as an AND, the values provided in the arrays are treated as an OR. |
Success - A notification has been created.
Bad request
Authentication required
Action is forbidden
Internal Server Error
Production Environment
Retrieves the notification containing filter information as well as notification template.
| notificationId required | string <uuid> Example: 09dc8207-43b8-40b8-a40f-c160bdf4d638 Notification Id |
Success - The notification.
Authentication required
Action is forbidden
Notification is not found
Internal Server Error
Production Environment
Request the notification to be updated.
With PUT it is expected that the complete notification blob is transferred with the request.
| notificationId required | string <uuid> Example: 09dc8207-43b8-40b8-a40f-c160bdf4d638 Notification Id |
| active required | boolean |
| notificationTemplate required | object Notification template |
| notificationFilter required | object Filter which allows to receive notifications for specific events; The filter conditions ("deviceEvent", "deviceId", "deviceTag", etc) are treated as an AND, the values provided in the arrays are treated as an OR. |
Success - The notification has been updated.
Bad request
Authentication required
Action is forbidden
Notification is not found
Internal Server Error
Production Environment
Request the notification to be updated.
With PATCH it is expected that a subset of the notification blob is transferred with the request.
For example, it could be only eventFilter or it could be combined with notificationTemplate and/or any other field.
| notificationId required | string <uuid> Example: 09dc8207-43b8-40b8-a40f-c160bdf4d638 Notification Id |
| active | boolean |
Success - The notification has been updated.
Bad request
Authentication required
Action is forbidden
Notification is not found
Internal Server Error
Production Environment
Request the notification to be deleted.
| notificationId required | string <uuid> Example: 09dc8207-43b8-40b8-a40f-c160bdf4d638 Notification Id |
Success - The notification has been deleted.
Authentication required
Action is forbidden
Notification is not found
Internal Server Error
Production Environment
Retrieves a list of all triggered notifications containing timestamp, what triggered notification and notification itself.
By default the list is sorted by creation datetime in descending order. So, most recently created entry goes first.
| page | integer >= 0 Default: 0 The number of the result page starting with 0. |
| pageSize | integer [ 1 .. 100 ] Default: 20 The number of result per page. |
| notificationId | Array of strings Example: notificationId=83b8c2a8-2e54-4ad0-8e96-313f99d433e3,abff5e9a-072d-4d4c-94f7-fd3515026bce Optional parameter to filter the list for certain notification ids |
Success - The notification history for a tenant.
Bad request
Authentication required
Action is forbidden
Internal Server Error
Production Environment
A Tenant is the entity owning everything except Users in the Lightelligence Platform. Devices, Device Types, Certificates etc. all belong to exactly one Tenant. Users can create Tenants and then add other users to the Tenant created Tenant.
Create a new Tenant.
| name required | string [ 3 .. 32 ] characters The name of the tenant |
| billingContact required | object The contact information of the person respnsible for the billing |
| billingCompany required | object The company information of the billing company |
| package required | object Package id of a tenant |
| payment required | object Payment details needed to process a payment with Adyen. Adyen is a global payment company that allows businesses to accept e-commerce, mobile, and point-of-sale payments. For more information about Adyen development you can check their documentation |
| contractId | string <= 127 characters Billing related contract id of the tenant |
Tenant creation successful
Bad Request response.
Forbidden
Conflict response.
Internal Server Error response.
This response means the resource(s) is currently down for maintenance
Production Environment
Get the tenant detailed information including billing information for the supplied tenantId.
Alternative endpoints:
Basic information of tenants can be fetched through the user self-management endpoints.
* /users/{userId}/tenants -> Listing all tenants available for user
* /users/{userId}/tenants/{tenantId} -> Get tenant with basic data including user roles
| tenantId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The tenant UUID. |
Success
Bad Request response.
Unauthorized response.
Forbidden
This response means you either do not have access to a specified resource or it does not even exist.
Internal Server Error response.
Production Environment
Update the tenant details with the supplied information.
| tenantId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The tenant UUID. |
| name | string [ 3 .. 32 ] characters The name of the tenant |
| billingContact | object The contact information of the person respnsible for the billing |
| billingCompany | object The company information of the billing company |
| package | object Package id of a tenant |
| payment | object Payment details needed to process a payment with Adyen. Adyen is a global payment company that allows businesses to accept e-commerce, mobile, and point-of-sale payments. For more information about Adyen development you can check their documentation |
| contractId | string <= 127 characters Billing related contract id of the tenant |
Success
Bad Request response.
Unauthorized response.
Forbidden
This response means you either do not have access to a specified resource or it does not even exist.
Internal Server Error response.
Production Environment
DEPRECATED, Please use GET /roles endpoint
Get the list of roles of a tenant.
| tenantId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The tenant UUID. |
Success
Bad Request response.
Unauthorized response.
Forbidden
This response means you either do not have access to a specified resource or it does not even exist.
Internal Server Error response.
Production Environment
The User object represents the data of a human being interacting with the Lightelligence Platform. It includes the name and also the e-mail address. A User can create a Tenant and then take actions inside this Tenant e.g. creating a Device.
Get the user details for the supplied userId.
| userId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The user UUID. |
Success
Bad Request response.
Unauthorized response.
Forbidden
This response means you either do not have access to a specified resource or it does not even exist.
Internal Server Error response.
Production Environment
Get the tenants of the provided user.
| userId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The user UUID. |
| page | integer >= 0 Default: 0 The number of the result page starting with 0. |
| pageSize | integer [ 1 .. 100 ] Default: 20 The number of results per page. |
Success
Bad Request response.
Unauthorized response.
Forbidden
This response means you either do not have access to a specified resource or it does not even exist.
Internal Server Error response.
Production Environment
Get tenant information for the provided tenant and user. This will only succeed if the user is part of the logged in tenant.
| userId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The user UUID. |
| tenantId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The tenant UUID. |
Success
Bad Request response.
Unauthorized response.
Forbidden
This response means you either do not have access to a specified resource or it does not even exist.
Internal Server Error response.
Production Environment
Get the list of permissions for the current user within the logged in tenant.
| userId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The user UUID. |
Success
Bad Request response.
Unauthorized response.
Forbidden
This response means you either do not have access to a specified resource or it does not even exist.
Internal Server Error response.
Production Environment
Get all invites for the current user.
| userId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The user UUID. |
| status | string Enum: "open" "accepted" "declined" Example: status=open The invite status to be filtered by |
| page | integer >= 0 Default: 0 The number of the result page starting with 0. |
| pageSize | integer [ 1 .. 100 ] Default: 20 The number of results per page. |
Success
Unauthorized response.
Forbidden
Internal Server Error response.
Production Environment
With this endpoint a user can accept or decline an invite. State changes are only possible for an invite with the status open. For example an already accepted invite can not be declined.
| userId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The user UUID. |
| inviteId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The invite UUID. |
| status required | string Enum: "open" "accepted" "declined" The status shows if the user accepted or declined the invite. |
Success - Invite updated
Bad Request response.
Unauthorized response.
Forbidden
Not found response.
Internal Server Error response.
Production Environment
User management is done within the context of a tenant. Here you can define which user has access to which tenant, by assigning or revoking roles. It's also possible to invite users that aren't registered with OLT yet by email.
Invite an user to a tenant.
| tenantId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The tenant UUID. |
| receiverEmail required | string <email> The email address of the invited user. |
| roleNames | Array of strings non-empty Deprecated Deprecated, please use |
| roles | Array of objects non-empty The IDs of the roles the user should be invited to. |
Success - Invite created
Bad Request response.
Unauthorized response.
Forbidden
Not found response.
Conflict response.
Internal Server Error response.
Production Environment
Get all invites to users for the provided tenant.
| tenantId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The tenant UUID. |
| status | string Enum: "open" "accepted" "declined" Example: status=open The invite status to be filtered by |
| page | integer >= 0 Default: 0 The number of the result page starting with 0. |
| pageSize | integer [ 1 .. 100 ] Default: 20 The number of results per page. |
Success
Bad Request response.
Unauthorized response.
Forbidden
Not found response.
Internal Server Error response.
Production Environment
Delete/Revoke the invite of a user to the tenant. Only open invites can be deleted.
| tenantId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The tenant UUID. |
| inviteId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The invite UUID. |
Success - No content
Bad Request response.
Unauthorized response.
Forbidden
Not found response.
Internal Server Error response.
Production Environment
Get the list of users associated to a tenant by any role.
| tenantId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The tenant UUID. |
| page | integer >= 0 Default: 0 The number of the result page starting with 0. |
| pageSize | integer [ 1 .. 100 ] Default: 20 The number of results per page. |
Success
Bad Request response.
Unauthorized response.
Forbidden
This response means you either do not have access to a specified resource or it does not even exist.
Internal Server Error response.
Production Environment
Remove a user from a tenant.
| tenantId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The tenant UUID. |
| userId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The user UUID. |
Success
Bad Request response.
Unauthorized response.
Forbidden
This response means you either do not have access to a specified resource or it does not even exist.
Internal Server Error response.
Production Environment
Get the list of users in the role within the tenant.
| roleId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The role UUID. |
| page | integer >= 0 Default: 0 The number of the result page starting with 0. |
| pageSize | integer [ 1 .. 100 ] Default: 20 The number of results per page. |
Success
Bad Request response.
Unauthorized response.
Forbidden
Internal Server Error response.
Production Environment
Get the list of roles for the user within the tenant.
| tenantId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The tenant UUID. |
| userId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The user UUID. |
| page | integer >= 0 Default: 0 The number of the result page starting with 0. |
| pageSize | integer [ 1 .. 100 ] Default: 20 The number of results per page. |
Success
Bad Request response.
Unauthorized response.
Forbidden
Internal Server Error response.
Production Environment
Change the roles of the user in the tenant.
| tenantId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The tenant UUID. |
| userId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The user UUID. |
| id required | string <uuid> UUID of a tenant role |
Success - Roles updated
Bad Request response.
Unauthorized response.
Forbidden
Not found response.
Internal Server Error response.
Production Environment
To interact with the API of OLT, a user needs to have the correct set of permissions. Using these permissions, a tenant can limit what actions a user can access within the Lightelligence Platform.
Get the list of permissions for the current user within the logged in tenant.
| userId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The user UUID. |
Success
Bad Request response.
Unauthorized response.
Forbidden
This response means you either do not have access to a specified resource or it does not even exist.
Internal Server Error response.
Production Environment
Get the list of permissions for the tenant. Permissions are the permissions which are required and checked within the OLT platform.
To interact with the API of OLT, the user needs to have the right set of permissions. Using these permissions, a tenant owner can limit what actions a user can access within the Lightelligence Platform.
Success
Bad Request response.
Forbidden
This response means you either do not have access to a specified resource or it does not even exist.
Internal Server Error response.
Production Environment
Create a new role connected to the logged in tenant.
Note: Support of alias in permissions will be dropped in future versions
All values can be updated after creation with PATCH: Update Role
| name required | string [ 3 .. 32 ] characters ^([a-zA-Z0-9_\- ]+)$ The name of the role |
| description | string Description of the role |
| permissions | Array of objects |
| customPermissions | Array of objects |
Success - Role created
Bad Request response.
Unauthorized response.
Forbidden
Conflict response.
Internal Server Error response.
Production Environment
Get the list of roles for the tenant including the list of permissions id's for each role.
| userId | string <uuid> Example: userId=123e4567-e89b-12d3-a456-426655440000 The user UUID. |
| page | integer >= 0 Default: 0 The number of the result page starting with 0. |
| pageSize | integer [ 1 .. 100 ] Default: 20 The number of results per page. |
Success
Bad Request response.
Unauthorized response.
Forbidden
Internal Server Error response.
Production Environment
Get details for the role.
| roleId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The role UUID. |
Success
Bad Request response.
Unauthorized response.
Forbidden
This response means you either do not have access to a specified resource or it does not even exist.
Internal Server Error response.
Production Environment
Delete role for tenant
| roleId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The role UUID. |
Success - No content
Bad Request response.
Unauthorized response.
Forbidden
Internal Server Error response.
Production Environment
Update the properties of a role. Which properties are modifiable can be viewed in the request body schema.
Note: Support of alias in permissions will be dropped in future versions
Note: Updating permissions or customPermissions will replace the entire list of permissions.
At least id or alias are required when updating permissions.
| roleId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The role UUID. |
| name | string [ 3 .. 32 ] characters ^([a-zA-Z0-9_\- ]+)$ The name of the role |
| description | string Description of the role |
| permissions | Array of objects |
| customPermissions | Array of objects |
Success - Role updated
Bad Request response.
Unauthorized response.
Forbidden
Not found response.
Conflict response.
Internal Server Error response.
Production Environment
Create a new custom permission for an application. Custom permissions - although managed via the OLT API - have no impact on the OLT platform whatsoever. Their sole purpose is to allow access control management within an application: By assigning a custom permission to a role, an external application can use this permission to allow/restrict resource access within that application. Custom permissions are specified within the scope of an application. A tenant owner can assign custom permissions of all installed application to all available roles within a tenant.
| applicationId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 An application id |
| alias required | string [ 3 .. 255 ] characters A computer readable identifier for the permission which will be used by the developers application |
| category required | string [ 3 .. 32 ] characters ^([a-zA-Z0-9_\- ]+)$ Used to group related permissions in the Custom Role Management User Interface for better overview |
| name required | string [ 3 .. 255 ] characters ^([a-zA-Z0-9_\- ]+)$ The human readable name of the permission, used in the Permission Management User Interface |
| description | string A human readable description of the purpose of the permission, used in the Custom Role Management User Interface |
Success
Bad Request response.
Unauthorized response.
Forbidden
This response means you either do not have access to a specified resource or it does not even exist.
Conflict response.
Internal Server Error response.
Production Environment
List all created custom permissions for an application.
| applicationId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 An application id |
| page | integer >= 0 Default: 0 The number of the result page starting with 0. |
| pageSize | integer [ 1 .. 100 ] Default: 20 The number of results per page. |
Success
Unauthorized response.
Forbidden
This response means you either do not have access to a specified resource or it does not even exist.
Internal Server Error response.
Production Environment
Get details of a specific custom permission.
| applicationId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 An application id |
| permissionId required | string <uuid> Example: 6e0c9341-02a0-43ad-a213-989f8c8a870f The permission ID. |
Succsess
Unauthorized response.
Forbidden
This response means you either do not have access to a specified resource or it does not even exist.
Internal Server Error response.
Production Environment
Update category or description of a specific custom permission. name and alias can only be changed by creating a new custom permission and deleting the old one.
| applicationId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 An application id |
| permissionId required | string <uuid> Example: 6e0c9341-02a0-43ad-a213-989f8c8a870f The permission ID. |
| category | string [ 3 .. 32 ] characters ^([a-zA-Z0-9_\- ]+)$ Used to group related permissions in the Custom Role Management User Interface for better overview |
| description | string A human readable description of the purpose of the permission, used in the Custom Role Management User Interface |
Success
Bad Request response.
Unauthorized response.
Forbidden
This response means you either do not have access to a specified resource or it does not even exist.
Internal Server Error response.
Production Environment
Not yet implemented Delete a specific custom permission. Note: Deleting a custom permission will also remove it from any roles it is assigned to.
| applicationId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 An application id |
| permissionId required | string <uuid> Example: 6e0c9341-02a0-43ad-a213-989f8c8a870f The permission ID. |
Success (No further content)
Bad Request response.
Unauthorized response.
Forbidden
This response means you either do not have access to a specified resource or it does not even exist.
Internal Server Error response.
Production Environment
This endpoint creates a new application for the tenant. The tenant of the user session will become the "owner" (also referred to as developer tenant) of the application. The redirectUris should be provided as a security mechanism to lock the OAuth2 callback URIs. Once the application got created, the oauth2Client.id of the application can be used as OAuth2 client ID and the oauth2Client.secret of the application must be used as the secret of the OAuth2 client. If the withPublicOauth2Client property was set, the oauth2PublicClient.id can also be used as OAuth2 client ID, but in this case without the secret.
To actually use the OAuth2 clients of the application a tenant must be added to the allowedTenants of the application and the tenant must install the application. Adding a tenant to the allowedTenants can be achieved by either providing the allowedTenants property directly with this request or later by using the PUT /allowed-tenants endpoint. To install the application the "user" tenant must use the POST /installation endpoint.
Note: To test the application as "owner", also the developer tenant must follow the steps for adding the developer tenant ID to the allowedTenants and install the application.
| name required | string [ 3 .. 32 ] characters ^([a-zA-Z0-9_\- ]+)$ The name of the application |
| teaserDescription | string <= 170 characters A short description for the application |
| url | string <url> <= 2000 characters A URL with more information on the app. E.g. the app homepage. Note: Protocol is required. |
| withPublicOauth2Client | boolean The |
| redirectUris | Array of strings List of redirect URIs. For security reasons, it's not allowed to use wildcards for any of the provided URIs. |
| allowedTenants | Array of objects List of allowed tenants for the application |
| permissions | object Permissions for this application |
Success - Application created
Bad Request
Unauthorized
Forbidden
Conflict
Internal Server Error
Production Environment
This endpoint lists all applications, which are developed by the tenant. The tenant is extracted from the current user session.
createdAt.| page | integer >= 0 Default: 0 The requested page |
| pageSize | integer [ 1 .. 100 ] Default: 20 The amount of results per page |
Success - List of developed applications
Bad Request
Unauthorized
Forbidden
Internal Server Error
Production Environment
Get detailed information for the developed application.
| applicationId required | string <uuid> Example: 570e0a66-974b-40dd-8108-844da77719e9 The application ID |
Success - Detailed Application Data
Bad Request
Unauthorized
Forbidden
Not found
Internal Server Error
Production Environment
Delete the developed application.
| applicationId required | string <uuid> Example: 570e0a66-974b-40dd-8108-844da77719e9 The application ID |
Success - Application deleted
Bad Request
Unauthorized
Forbidden
Not found
Internal Server Error
Production Environment
Update details of the developed application. When the status property of the application is updated to "inactive", the application cannot be installed and does not have access to any tenants' data anymore.
| applicationId required | string <uuid> Example: 570e0a66-974b-40dd-8108-844da77719e9 The application ID |
| name | string [ 3 .. 32 ] characters ^([a-zA-Z0-9_\- ]+)$ The name of the application |
| teaserDescription | string <= 170 characters A short description for the application |
| url | string <url> <= 2000 characters A URL with more information on the app. E.g. the app homepage. Note: Protocol is required. |
| withPublicOauth2Client | boolean The |
| status | string Enum: "active" "inactive" Status of the application. An |
| redirectUris | Array of strings List of redirect URIs. For security reasons, it's not allowed to use wildcards for any of the provided URIs. |
| permissions | object Permissions for this application |
Success - Application updated
Bad Request
Unauthorized
Forbidden
Not found
Internal Server Error
Production Environment
List tenants that can install the application.
| applicationId required | string <uuid> Example: 570e0a66-974b-40dd-8108-844da77719e9 The application ID |
| page | integer >= 0 Default: 0 The requested page |
| pageSize | integer [ 1 .. 100 ] Default: 20 The amount of results per page |
Success - List of allowed tenants
Bad Request
Unauthorized
Forbidden
Not found
Internal Server Error
Production Environment
This endpoint allows a specific tenant to install the application as after creating a new application no tenant is allowed to access it. The passed tenanatId will not be verified for existence, but one may use the comment property, to better identify the tenant. Once the tenant successfully installed the application, the installed flag will be set to true and the tenantName will be available.
| applicationId required | string <uuid> Example: 570e0a66-974b-40dd-8108-844da77719e9 The application ID |
| tenantId required | string <uuid> Example: 570e0a66-974b-40dd-8108-844da77719e9 The tenant ID |
| comment | string [ 0 .. 255 ] characters A comment about the allowed tenant. As there is no validation of the |
Success - Allowed tenant added
Bad Request
Unauthorized
Forbidden
Internal Server Error
Production Environment
Remove access for the tenant to use the application and don't allow the tenant to install the application anymore.
| applicationId required | string <uuid> Example: 570e0a66-974b-40dd-8108-844da77719e9 The application ID |
| tenantId required | string <uuid> Example: 570e0a66-974b-40dd-8108-844da77719e9 The tenant ID |
Success - Allowed tenant removed
Bad Request
Unauthorized
Forbidden
Not found
Internal Server Error
Production Environment
Generate a new secret for the application. Once the new secret is generated the old one will not work anymore.
| applicationId required | string <uuid> Example: 570e0a66-974b-40dd-8108-844da77719e9 The application ID |
Success - Application secret created
Bad Request
Unauthorized
Forbidden
Internal Server Error
Production Environment
Endpoints for a user to access available applications, install and uninstall these and more for application management to your tenants applications.
Lists all applications available for the tenant. This includes both the currently installed applications of the tenant and the applications available for installation. By using the installed query parameter the response can be filtered for only installed applications. The tenant is extracted from the current user session.
| installed | boolean Example: installed=true Filter for only installed applications |
| page | integer >= 0 Default: 0 The requested page |
| pageSize | integer [ 1 .. 100 ] Default: 20 The amount of results per page |
Success - List of applications
Bad Request
Unauthorized
Forbidden
Internal Server Error
Production Environment
Get detailed information for the available or installed application.
| applicationId required | string <uuid> Example: 570e0a66-974b-40dd-8108-844da77719e9 The application ID |
Success - Application Details
Bad Request
Unauthorized
Forbidden
Not found
Internal Server Error
Production Environment
Installs the application for the requesting tenant. The request must contain the full set of user and client permissions that are assigned to the application, otherwise the installation will fail. If an installation for that application already exists the request will fail.
| applicationId required | string <uuid> Example: 570e0a66-974b-40dd-8108-844da77719e9 The application ID |
| permissions required | object Permissions for this application |
Success - Application installed
Bad Request
Unauthorized
Forbidden
Not found
Conflict
Internal Server Error
Production Environment
Fetch details of an application installation.
| applicationId required | string <uuid> Example: 570e0a66-974b-40dd-8108-844da77719e9 The application ID |
Success - Installation details
Bad Request
Unauthorized
Forbidden
Not found
Internal Server Error
Production Environment
Updates and re-consents an installation. The request must contain the full set of user and client permissions that are assigned to the application, otherwise the request will fail. If an installation for that application doesn't exist the request will fail.
| applicationId required | string <uuid> Example: 570e0a66-974b-40dd-8108-844da77719e9 The application ID |
| permissions required | object Permissions for this application |
Success - Application installation updated
Bad Request
Unauthorized
Forbidden
Not found
Conflict
Internal Server Error
Production Environment
Uninstalls the application assigned to the tenant. Once the application has been uninstalled, it cannot access any data of the tenant anymore.
| applicationId required | string <uuid> Example: 570e0a66-974b-40dd-8108-844da77719e9 The application ID |
Success - Application uninstalled
Bad Request
Unauthorized
Forbidden
Not found
Internal Server Error
Production Environment
Fetch permissions that is required by application
| applicationId required | string <uuid> Example: 570e0a66-974b-40dd-8108-844da77719e9 The application ID |
Success - Application permissions
Bad Request
Unauthorized
Forbidden
Not found
Internal Server Error
Production Environment
Endpoints accessible only for your applications. Access by using client_credentials OAuth2 grant flow.
Lists the tenants installed for the application. This endpoint can only be called from the application itself, with an access token. It gets the access token via the client credentials flow. The access token is not associated with a tenant.
| page | integer >= 0 Default: 0 The requested page |
| pageSize | integer [ 1 .. 100 ] Default: 20 The amount of results per page |
Success - List of installed tenants
Bad Request
Unauthorized
Forbidden
Not found
Internal Server Error
Production Environment
Determines the installation details for the client-tenant-combination given by the provided access token. Must be called with access token
Success - Installation details
Unauthorized
Not found
Internal Server Error
Production Environment
Devices are the things inside of the Lightelligence Platform. Devices reach from a small sensor unit over a mid sized gateway with internet connection to a full blown installation controller. Devices can be connected to the cloud by assigning an certificate or connecting it over another Device.
Registers a new device for your Lightelligence tenant. If a configuration is provided and the device is connected to a gateway via connectedBy, the gateway will receive a configuration update via MQTT.
| info required | object |
| configuration | object Object describing the desired device configuration properties. If this is changed, the device will receive an MQTT message containing the new configuration. |
| custom | object Place for custom data. |
Success - created device.
Bad Request response.
Unauthorized response.
Forbidden response.
The device to use as connectedBy was not found.
Internal Server Error response.
Production Environment
This endpoint returns a list of devices, ordered by creation date from newest to oldest. The list can be filtered by provided filter. Filter entries can be either provided as query parameters or in the request body, but not both. Each of these filters has to match, so if multiple are provided, the device has to match both filters. For each of the filters, multiple values can be provided. If multiple values are provided, the filter matches if the device matches any of the provided values. So if for example multiple device tags are provided, any device having at least one of the tags is returned.
| page | integer >= 0 Default: 0 The number of the result page starting with 0. |
| pageSize | integer >= 0 Default: 20 The number of result per page. |
| deviceId | Array of strings <uuid> non-empty Example: deviceId=eba878ba-4a5d-4e67-b9d4-4dfd4e55f32f,be838a54-5f85-4154-b8a6-81fa4cb29561 A comma separated list of device Ids which you want to use as a filter. Device will be selected if matches at least one item in a list |
| deviceTag | Array of strings non-empty Example: deviceTag=tag1,tag1 Filter the results to contain devices having one of the comma-separated list of tags provided here. Case-insensitive. Surround the tag with * for substring matching. Example: |
| deviceTypeId | Array of strings <uuid> non-empty Example: deviceTypeId=e41bcf5e-2a4e-435a-8387-4617cd52b194,f86579db-f403-4ce1-b782-f1978733ef9b Filter returning results matching one of the provided device type IDs. |
| deviceTypeCategory | Array of strings <uri> non-empty Example: deviceTypeCategory=urn%3Aexample%3Atest1%3Acategory,urn%3Aexample%3Atest2%3Acategory Filter the results to contain only entries having at least one of the provided categories. Example: [urn:example:test:category] |
| deviceConnectedBy | Array of strings <uuid> non-empty Example: deviceConnectedBy=eba878ba-4a5d-4e67-b9d4-4dfd4e55f32f,be838a54-5f85-4154-b8a6-81fa4cb29561 Filter the results to contain devices having one of the comma-separated list of 'connected by' provided here. |
| deviceName | Array of strings non-empty Example: deviceName=Living%2A,Bad%2A Filter the results to contain devices having one of the comma-separated list of names provided here. Case-insensitive. Surround with * for substring matching. Example: subString OR fullMatchingName |
| deviceAlias | Array of strings non-empty Example: deviceAlias=Living%2A,Bad%2A Filter returning devices matching a one of device aliases. Supports wildcards using '*'. Example: 06-00-00-00-00-00 OR alias |
| deviceId | Array of strings <uuid> non-empty A list of device ids |
| deviceConnectedBy | Array of strings <uuid> non-empty A list of device ids |
| deviceTag | Array of strings non-empty A list of device tags |
| deviceName | Array of strings non-empty A list of device names. Supports wildcards using '*'. Case insensitive |
| deviceTypeName | Array of strings non-empty A list of device type names. Supports wildcards using '*'. Case insensitive |
| deviceTypeCategory | Array of strings <uri> non-empty A list of device type categories |
| deviceTypeId | Array of strings <uuid> non-empty A list of device type ids |
| deviceAlias | Array of strings non-empty A list of device aliases. Supports wildcards using '*' |
Success - requested devices.
Bad Request response.
Unauthorized response.
Forbidden response.
Internal Server Error response.
Production Environment
Get a device by its UUID.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices UUID. |
Success - requested device.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
Internal Server Error response.
Production Environment
Edit the device's data. Updating the configuration of a device will trigger a configuration synchronization message that will be sent to the device or the gateway, which the device is connected to, via MQTT.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices UUID. |
| info | object |
| configuration | object Object describing the desired device configuration properties. If this is changed, the device will receive an MQTT message containing the new configuration. |
| tags | Array of strings An array of tags to easily sort the devices (case insensitive and will be converted to lowercase). |
| custom | object Place for custom data. |
Success - edited the devices data.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
Internal Server Error response.
Production Environment
Delete a device by its UUID.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices UUID. |
Success - device deleted.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
Internal Server Error response.
Production Environment
Edit the online monitoring configurations for a device by UUID
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices UUID. |
| communicationInterval required | integer [ 0 .. 172800 ] Nullable Expected communication interval in seconds for online monitoring of a device. When set to zero the online monitoring is disabled. When set to NULL on a device, the interval value from the associated device type will be inherited. When set to NULL on a device type, it will also disable the monitoring, unless any associated device overrides it with a non-zero value. Non-NULL device interval values always take precedence over device type interval values." |
Success - edited online monitoring configuration of device.
Bad Request response.
Unauthorized response.
Forbidden or not found response.
Production Environment
Get the online monitoring configurations for a device by UUID
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices UUID. |
Success - requested online monitoring configurations for a device.
Bad Request response.
Unauthorized response.
Forbidden or not found response.
Production Environment
The action name and payload will be transmitted to the device via MQTT.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices UUID. |
| action required | string Name of the action |
| payload required | object Action properties, validated against the schema actions in device type. |
Success - action accepted
Bad Request response.
Unauthorized response.
Not Found response.
Internal Server Error response.
Production Environment
The action name and payload will be transmitted to the devices matching the given filter via MQTT. The action will only be sent to the devices where it matches the schema of the device type.
| action required | string Name of the action |
| payload required | object Action properties, validated against the schema actions in device type. |
| deviceFilter required | object |
Bulk actions request was accepted.
Bad Request response.
Unauthorized response.
Internal Server Error response.
Production Environment
Get the current state of a device. Device state contains the latest values for attributes and configuration, as sent by the device.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices uuid. |
Success - the device's state.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
Internal Server Error response.
Production Environment
Get the current state of each Device which matches the provided filter, ordered by creation date from newest to oldest. The state of a Device contains the latest value of each attribute and configuration.
| page | integer >= 0 Default: 0 The number of the result page starting with 0. |
| pageSize | integer >= 0 Default: 20 The number of result per page. |
| deviceId | Array of strings <uuid> non-empty Example: deviceId=eba878ba-4a5d-4e67-b9d4-4dfd4e55f32f,be838a54-5f85-4154-b8a6-81fa4cb29561%22 A comma separated list of device Ids which you want to use as a filter. Device will be selected if matches at least one item in a list |
| deviceTag | Array of strings non-empty Example: deviceTag=tag1,tag1 Filter the results to contain devices having one of the comma-separated list of tags provided here. Case-insensitive. Surround the tag with * for substring matching. Example: |
| deviceTypeId | Array of strings <uuid> non-empty Example: deviceTypeId=e41bcf5e-2a4e-435a-8387-4617cd52b194,f86579db-f403-4ce1-b782-f1978733ef9b Filter returning results matching one of the provided device type IDs. |
| deviceTypeCategory | Array of strings <uri> non-empty Example: deviceTypeCategory=urn%3Aexample%3Atest1%3Acategory,urn%3Aexample%3Atest2%3Acategory Filter the results to contain only entries having at least one of the provided categories. Example: [urn:example:test:category] |
| deviceConnectedBy | Array of strings <uuid> non-empty Example: deviceConnectedBy=eba878ba-4a5d-4e67-b9d4-4dfd4e55f32f,be838a54-5f85-4154-b8a6-81fa4cb29561%22 Filter the results to contain devices having one of the comma-separated list of 'connected by' provided here. |
| deviceName | Array of strings non-empty Example: deviceName=Living%2A,Bad%2A Filter the results to contain devices having one of the comma-separated list of names provided here. Case-insensitive. Surround with * for substring matching. Example: subString OR fullMatchingName |
| deviceAlias | Array of strings non-empty Example: deviceAlias=Living%2A,Bad%2A Filter returning devices matching a one of device aliases. Supports wildcards using '*'. Example: 06-00-00-00-00-00 OR alias |
| deviceId | Array of strings <uuid> non-empty A list of device ids |
| deviceConnectedBy | Array of strings <uuid> non-empty A list of device ids |
| deviceTag | Array of strings non-empty A list of device tags |
| deviceName | Array of strings non-empty A list of device names. Supports wildcards using '*'. Case insensitive |
| deviceTypeName | Array of strings non-empty A list of device type names. Supports wildcards using '*'. Case insensitive |
| deviceTypeCategory | Array of strings <uri> non-empty A list of device type categories |
| deviceTypeId | Array of strings <uuid> non-empty A list of device type ids |
| deviceAlias | Array of strings non-empty A list of device aliases. Supports wildcards using '*' |
Success - the requested devices states.
Bad Request response.
Unauthorized response.
Forbidden response.
Internal Server Error response.
Production Environment
Retrieve the events received inside last hour, latest first. Events can be filtered by their type. Note: This endpoint should only be used for debugging.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices uuid. |
| eventTypes | Array of strings Example: eventTypes=type1%2Ctype2%2Ctype3 A comma separated list of event types used as a filter. So only events with one of these types assigned will be returned. |
Success - the device's events.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
Internal Server Error response.
Production Environment
Assign a certificate to a device. The certificate can then be used for authenticating the device when it connects to Lightelligence, for example through MQTT. A certificate can only be assigned to exactly one device.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices UUID. |
| cert required | string The certificate |
| status required | string Default: "valid" Enum: "valid" "expired" "revoked" "inactive" The status of the certificate. |
Success - certificate.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
Resource to create conflicts with an existing one.
Internal Server Error response.
Production Environment
Provides a list of the certificates assigned to this device, ordered by creation date from newest to oldest.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices UUID. |
| page | integer >= 0 Default: 0 The number of the result page starting with 0. |
| pageSize | integer >= 0 Default: 20 The number of result per page. |
Success - certificate.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
Internal Server Error response.
Production Environment
Get the details of the certificate associated with a device.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices UUID. |
| certId required | string <uuid> The certificate UUID. |
Success - certificate.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
Internal Server Error response.
Production Environment
Edit the details of the certificate associated with a device.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices UUID. |
| certId required | string <uuid> The certificate UUID. |
| status | string Default: "valid" Enum: "valid" "expired" "revoked" "inactive" The status of the certificate. |
Success - certificate.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
Internal Server Error response.
Production Environment
Delete the certificate associated with a device.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices UUID. |
| certId required | string <uuid> The certificate UUID. |
Success - certificate deleted.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
Internal Server Error response.
Production Environment
Get diagnostics data for the last hour, as reported for the device with the given UUID. Device Diagnostics contain errors in handling the data from the device on the cloud side. Data will be returned in descending order.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The device to filter for (uuid) |
OK
Bad Request response.
Unauthorized response.
Not Found response.
Internal Server Error response.
Production Environment
This endpoint creates a new firmware installation resource. This resource represents the status of installation into the slot for the specific device. Once it created, the device start receives installation instructions via MQTT.
| deviceId required | string <uuid> The device ID |
Firmware installation to add to the system.
| firmwareId required | string <uuid> The UUID of the firmware. |
| slot required | string <= 255 characters ^([a-zA-Z0-9_]+)$ The name of the slot for firmware installation. |
Firmware installation was successfully created.
Your request could not be processed. This could e.g. mean that the provided JSON is not valid and cannot be parsed or that the object submitted to a POST or PATCH request failed to validate against JSON schema.
Your request is not authorized. This response means that you are not authorized to get access to the requested resource.
This response means you either do not have access to a specified resource or it does not even exist. The difference will not be exposed to the user to make iterating that much harder.
Internal Server Error response.
Production Environment
This endpoint returns a list of firmware installations for a device.
| deviceId required | string <uuid> The device ID |
| latestOnly | boolean Default: false The flag that allows returning only the latest successful installation per slot |
OK
Your request is not authorized. This response means that you are not authorized to get access to the requested resource.
This response means you either do not have access to a specified resource or it does not even exist. The difference will not be exposed to the user to make iterating that much harder.
Internal Server Error response.
Production Environment
This endpoint returns a firmware-installation for the specified UUID.
| deviceId required | string <uuid> The device ID |
| installationId required | string <uuid> The firmware installation ID |
OK
Your request is not authorized. This response means that you are not authorized to get access to the requested resource.
This response means you either do not have access to a specified resource or it does not even exist. The difference will not be exposed to the user to make iterating that much harder.
Internal Server Error response.
Production Environment
This endpoint enables updating the status of firmware installation for a device. This installation status is tracking on the cloud side. Used by devices/gateways/analytics/etc which report statuses of the installation firmware into the slot.
| deviceId required | string <uuid> The device ID |
| installationId required | string <uuid> The firmware installation ID |
| startedAt required | string <date-time> The date when the firmware installation was started on device-side |
| completedAt | string <date-time> The date when the firmware installation was successfully completed on device-side |
| rejectedAt | string <date-time> The date when the firmware installation was rejected on device-side, due to some error |
| rejectReason | string <= 255 characters The description of firmware installation rejection |
OK
Your request is not authorized. This response means that you are not authorized to get access to the requested resource.
This response means you either do not have access to a specified resource or it does not even exist. The difference will not be exposed to the user to make iterating that much harder.
Internal Server Error response.
Production Environment
Get aggregated timeseries data for the device with the given UUID. Data will be returned in descending order. Maximum 4000 data points are returned.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices uuid. |
| startTime required | string <date-time> The start time of the time frame to request. |
| endTime required | string <date-time> The end time of the time frame to request. |
| frameSize | string Enum: "1m" "5m" "30m" "1h" "1d" The time frame size in which the values should be aggregated. By default, no frameSize is set and the data is not grouped by time. This means that the response contains exactly one result. In case frameSize is set and the number of points in the response exceed 4000, an error (400) will be returned. |
| aggregation required | string Enum: "min" "max" "mean" "sum" "count" "diff" "first" "last" Example: aggregation=max How should the values be aggregated. Supported values: min, max, mean, sum, count, diff, first, last. |
| path required | string Example: path=%24.attributes.sensor.brightness Path matching to a path defined in the reporting rules of the device's type. (e.g. |
Success - data.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
Internal Server Error response.
Production Environment
Get timeseries data for the last hour, as reported by the device with the given UUID. Data will be returned in an descending order. Maximum 4000 data points are returned. Note: This endpoint should be used by the user only for debugging his devices and the data they send.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices uuid. |
| path required | string Example: path=%24.attributes.sensor.brightness Path matching to a path defined in the reporting rules of the device's type. (e.g. |
Success - sensordata.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
Internal Server Error response.
Production Environment
Delete reported timeseries data of a device belonging to the given UUID. This deletes both the timeseries and its aggregation. If no timeframe is provided, all data for the device and path is deleted.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices uuid. |
| path required | string Example: path=%24.attributes.sensor.brightness Path matching to a path defined in the reporting rules of the device's type. (e.g. |
| startTime | string <date-time> The start time of the time frame to request. (RFC 3339) |
| endTime | string <date-time> The end time of the time frame to request. (RFC 3339) |
Success.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
Internal Server Error response.
Production Environment
Create a new timeseries dump, as reported by the device with the given UUID. The dump will be created asynchronously, and once completed will be available in the URL returned by this route. If no start and end time are specified, the dump contains all available data.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices uuid. |
| path required | string Path matching to a path defined in the reporting rules of the device's type. (e.g. |
| startTime | string <date-time> The dump contains data starting with the start time (RFC 3339) |
| endTime | string <date-time> The dump contains data starting till to the end time (RFC 3339) |
Success
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
Internal Server Error response.
Production Environment
Return a timeseries dump created asynchronously via a POST request. If the dump is not yet ready, this route will respond with a 404. All created dumps will expire after one hour.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices uuid. |
| dumpId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The UUID of the dump |
A JSON file
Bad Request response.
Unauthorized response.
Forbidden response.
Dump not found
Internal Server Error response.
Production Environment
Create a new dump of selected timeseries data. The dump will be created asynchronously, and once completed will be available in the URL returned by this route.
| dataFilter required | object |
| deviceFilter required | object Criteria for filtering data by device. If multiple filters of different types (for example, tags and aliases) are provided, the devices must match each of them. You need to provide at least one device filter. |
Success
Bad Request response.
Unauthorized response.
This response means you either do not have access to a specified resource or it does not even exist. The difference will not be exposed to the user to make iterating that much harder.
Internal Server Error response.
Production Environment
Return a timeseries dump created asynchronously via a POST request. If the dump is not yet ready, this route will respond with a 404. All created dumps will expire after one hour.
| dumpId required | string <uuid> Example: 07aba39a-ccb3-426f-838e-6d9a9ae330f4 The UUID of the dump |
A JSON file
Bad Request response.
Unauthorized response.
This response means you either do not have access to a specified resource or it does not even exist. The difference will not be exposed to the user to make iterating that much harder.
Dump not found
Internal Server Error response.
Production Environment
Get aggregated timeseries data points for the devices matching the given filters. The data dump will be created asynchronously, and once completed will be available at the URL returned by this route. Data points in the dump will be sorted chronologically from newest to oldest.
| dataFilter required | object |
| params required | object |
| deviceFilter required | object Criteria for filtering data by device. If multiple filters of different types (for example, tags and aliases) are provided, the devices must match each of them. You need to provide at least one device filter. |
Request accepted
Bad Request response.
Unauthorized response.
This response means you either do not have access to a specified resource or it does not even exist. The difference will not be exposed to the user to make iterating that much harder.
Internal Server Error response.
Production Environment
Return an aggregated timeseries data dump created asynchronously via a POST request. If the dump is not yet ready, this route will respond with a 404. All created dumps will expire after one hour. Data points in the dump will be sorted chronologically from newest to oldest.
| dumpId required | string <uuid> Example: 07aba39a-ccb3-426f-838e-6d9a9ae330f4 The UUID of the dump |
A JSON file
Bad Request response.
Unauthorized response.
This response means you either do not have access to a specified resource or it does not even exist. The difference will not be exposed to the user to make iterating that much harder.
Dump not found
Internal Server Error response.
Production Environment
Request a new WebSocket connection URL. If the request and authentication is successful the provided URL from the response can be used to establish a new WebSocket connection.
The stream capabilities depend on its type.
live stream: service starts streaming events once connection is established.
When client reconnects again, stream starts from the point of connection. Events that
happened when client was disconnected are dropped.
buffered stream: service starts buffering events once connected. Events streamed from the persistent storage,
so there is might be some latency comparing to live streams. Events stay in the buffer for 2 days.
It means if time between reconnections is shorter than 2 days, already consumed events can be deliverd again.
The age of events to deliver is specified by options.replayFromTimestamp parameter.
If the client wouldn't make any new connections longer than 2 days after last disconnect, the service will
stop buffering for the given client.
Note: The WebSocket connection URL is only valid for 15 seconds. If the url has expired, a new url needs to be requested.
| type | string Enum: "live" "buffered" Specify the type of streaming connection requested. Defaults to "live". Live connections instantly sends messages received to the WebSocket connection, whereas buffered connection starts buffering messages for tenant on first connection. If connection is lost, messages that are up to two days old can be replayed. |
| options | object Specify options for the streaming connection. Not necessary on first connection. |
| filter required | object Filter which allows to receive updates for specific message types and devices; The five filter conditions ("type", "deviceId", "tag", "attributes" and "configurations") are treated as an AND, the values provided in the arrays are treated as an OR. So the websocket client will receive all messages that contains ONE of the mentioned message types AND originates from ONE of the mentioned device ids. |
Success - A new WebSocket connection can be established with the provided WebSocket URL in the response.
Bad request
Unauthorized
Token is not valid
Internal Server Error
Production Environment
IMPORTANT NOTE: this path is likely to change, DO NOT RELY ON THE EXACT PATH, just take the URL that is returned from the POST as is.
time to order the messages received in the client.| token required | string <string> Example: bbdf5d13d9a09ab5cfe5c45536ecf4f432e9c4736aeb6d930ea240904d0ae7d8 The token used to authenticate the WebSocket connection |
Token is not valid
Internal Server Error
Production Environment
IMPORTANT NOTE: DO NOT RELY ON THE EXACT PATH, just take the URL that is returned from the POST as is.
time to order the messages received in the client.| token required | string <string> Example: bbdf5d13d9a09ab5cfe5c45536ecf4f432e9c4736aeb6d930ea240904d0ae7d8 The token used to authenticate the WebSocket connection |
| type required | string Enum: "live" "buffered" Example: live The streaming type |
Token is not valid
Internal Server Error
Production Environment
Device Types are used to describe the behaviour of a Device. This includes the schema of the data a Device reports or receives as well as information like model and description. Furthermore the Device Type specifies, where reported data is saved in the cloud by including reporting rules.
Registers a new device type that can be used for Lightelligence devices.
| name required | string <= 255 characters Name of the device type |
| manufacturer | string <= 255 characters The manufacurer of the device. |
| model | string <= 255 characters The model of the device |
| description | string <= 255 characters A descriptive text. |
| categories | Array of strings <uri> External specifications the device conforms to |
| reportingRules | Array of objects Reporting rules for various attributes or configuration keys of the device. Unless specified, everything is reported to deviceManagement |
| schema required | object JSON Schemas for the inputs and outputs of the device |
| slots | object JSON Slots for device type |
| communicationInterval | integer [ 0 .. 172800 ] Nullable Expected communication interval in seconds for online monitoring of a device. When set to zero the online monitoring is disabled. When set to NULL on a device, the interval value from the associated device type will be inherited. When set to NULL on a device type, it will also disable the monitoring, unless any associated device overrides it with a non-zero value. Non-NULL device interval values always take precedence over device type interval values." |
Success - device-type added.
Bad Request response.
Unauthorized response.
Forbidden response.
Internal Server Error response.
Production Environment
Provides a list of device types available for your tenant, ordered by creation date from newest to oldest. The list can be filtered by name, semantic categories or device type ids. Filter entries can be either provided as query parameters or in the request body, but not both.
| page | integer >= 0 Default: 0 The number of the result page starting with 0. |
| pageSize | integer >= 0 Default: 20 The number of result per page. |
| deviceTypeName | Array of strings non-empty Example: deviceTypeName=Living%2A,Bad%2A Filter the results to contain device types having one of the comma-separated list of names provided here. Case-insensitive. Surround with * for substring matching. Example: subString OR fullMatchingName |
| deviceTypeCategory | Array of strings <uri> non-empty Example: deviceTypeCategory=urn%3Aexample%3Atest1%3Acategory,urn%3Aexample%3Atest2%3Acategory Filter the results to contain only entries having at least one of the provided categories. Example: [urn:example:test:category] |
| deviceTypeId | Array of strings <uuid> non-empty Example: deviceTypeId=e41bcf5e-2a4e-435a-8387-4617cd52b194,f86579db-f403-4ce1-b782-f1978733ef9b Filter returning results matching one of the provided device type IDs. |
| deviceTypeName | Array of strings non-empty A list of device type names. Supports wildcards using '*'. Case insensitive |
| deviceTypeCategory | Array of strings <uri> non-empty A list of device type categories |
| deviceTypeId | Array of strings <uuid> non-empty A list of device type ids |
Success - device-types
Bad Request response.
Unauthorized response.
Internal Server Error response.
Production Environment
Provides a list of semantic categories used in your device types.
Success - device-types-categories
Bad Request response.
Unauthorized response.
Internal Server Error response.
Production Environment
Get a specific device type by UUID
| deviceTypeId required | string <uuid> The device type id. |
Success - requested device-type.
Bad Request response.
Unauthorized response.
Not Found response.
Internal Server Error response.
Production Environment
Edit a specific device type by UUID partially. UUID is not patchable. You can also only patch a single property from your custom data. Provide a null to delete a property.
| deviceTypeId required | string <uuid> The device type id. |
| name | string [ 1 .. 255 ] characters Name of the device type |
| manufacturer | string <= 255 characters Nullable The manufacurer of the device. |
| model | string <= 255 characters Nullable The model of the device |
| description | string <= 255 characters Nullable A descriptive text. |
| categories | Array of strings <uri> Nullable External specifications the device conforms to |
| reportingRules | Array of objects Nullable Reporting rules for various attributes or configuration keys of the device. Unless specified, everything is reported to deviceManagement |
| schema | object JSON Schemas for the inputs and outputs of the device |
| slots | object JSON Slots for device type |
| communicationInterval | integer [ 0 .. 172800 ] Nullable Expected communication interval in seconds for online monitoring of a device. When set to zero the online monitoring is disabled. When set to NULL on a device, the interval value from the associated device type will be inherited. When set to NULL on a device type, it will also disable the monitoring, unless any associated device overrides it with a non-zero value. Non-NULL device interval values always take precedence over device type interval values." |
Success - edited device-type.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
The device to use as connectedBy was not found.
Internal Server Error response.
Production Environment
Delete a specific device type by UUID. Device types currently associated with devices cannot be removed.
| deviceTypeId required | string <uuid> The device type id. |
Success - deleted device-type.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
DeviceType can not be deleted. It is being used by active devices.
Internal Server Error response.
Production Environment
Edit the online monitoring configurations for a device type by UUID
| deviceTypeId required | string <uuid> The device type id. |
| communicationInterval required | integer [ 0 .. 172800 ] Nullable Expected communication interval in seconds for online monitoring of a device. When set to zero the online monitoring is disabled. When set to NULL on a device, the interval value from the associated device type will be inherited. When set to NULL on a device type, it will also disable the monitoring, unless any associated device overrides it with a non-zero value. Non-NULL device interval values always take precedence over device type interval values." |
Success - edited online monitoring configuration of device-type.
Bad Request response.
Unauthorized response.
Forbidden or not found response.
Production Environment
Get the online monitoring configurations for a device type by UUID
| deviceTypeId required | string <uuid> The device type id. |
Success - requested online monitoring configurations for a device-type.
Bad Request response.
Unauthorized response.
Forbidden or not found response.
Production Environment
Associate an existing firmware with a slot in the provided device type. After this, the firmware can be installed into the slot on all devices having this device type.
| deviceTypeId required | string <uuid> The device type id. |
| slotName required | string <= 255 characters ^([a-zA-Z0-9_]+)$ The device type slot name. |
| firmwareId required | string <uuid> Device firmware UUID |
Success - associated device type firmwares.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
The device to use as connectedBy was not found.
Internal Server Error response.
Production Environment
Retrieve the list of firmwares associcated with the specified slot on the specified device type. All the firmwares listed here can be installed into the slot on all devices having this device type
| deviceTypeId required | string <uuid> The device type id. |
| slotName required | string <= 255 characters ^([a-zA-Z0-9_]+)$ The device type slot name. |
Success - requested device type firmwares.
Bad Request response.
Unauthorized response.
Not Found response.
Internal Server Error response.
Production Environment
Removal of an association for a slot in specified device type. After removal of an association, all existing installation and installation requests will continue to run.
| deviceTypeId required | string <uuid> The device type id. |
| slotName required | string <= 255 characters ^([a-zA-Z0-9_]+)$ The device type slot name. |
| associationId required | string <uuid> The association id. |
Success - removal of an association.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
Internal Server Error response.
Production Environment
Certificates are used to authenticate a Device when it connects to the cloud. Therefore every Device which directly sends data to the cloud needs to have a certificate. If a Device A sends data to a Device B (acting as a gateway) which sends the data to the cloud. Device A does not need a certificate, only device B does.
Assign a certificate to a device. The certificate can then be used for authenticating the device when it connects to Lightelligence, for example through MQTT. A certificate can only be assigned to exactly one device.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices UUID. |
| cert required | string The certificate |
| status required | string Default: "valid" Enum: "valid" "expired" "revoked" "inactive" The status of the certificate. |
Success - certificate.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
Resource to create conflicts with an existing one.
Internal Server Error response.
Production Environment
Provides a list of the certificates assigned to this device, ordered by creation date from newest to oldest.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices UUID. |
| page | integer >= 0 Default: 0 The number of the result page starting with 0. |
| pageSize | integer >= 0 Default: 20 The number of result per page. |
Success - certificate.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
Internal Server Error response.
Production Environment
Get the details of the certificate associated with a device.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices UUID. |
| certId required | string <uuid> The certificate UUID. |
Success - certificate.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
Internal Server Error response.
Production Environment
Edit the details of the certificate associated with a device.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices UUID. |
| certId required | string <uuid> The certificate UUID. |
| status | string Default: "valid" Enum: "valid" "expired" "revoked" "inactive" The status of the certificate. |
Success - certificate.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
Internal Server Error response.
Production Environment
Delete the certificate associated with a device.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices UUID. |
| certId required | string <uuid> The certificate UUID. |
Success - certificate deleted.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
Internal Server Error response.
Production Environment
Firmware resources represent files that can be pushed down or pulled by gateways and/or devices. Each firmware resource consists of some metadata, providing additional information like a version or description, and an attached file (blob). These files can be firmwares, bootloaders, configuration files or any binary data you want to manage.
This endpoint creates a new firmware resource. Once a firmware is created, arbitrary blob data can be attached to the firmware resource. Blob data can be a firmware file, configuration file or any other binary data. Firmware resources without attached blob data will become invalid after 5 minutes.
Firmware to add to the system
| name required | string [ 1 .. 255 ] characters The name of the firmware |
| description | string <= 255 characters Nullable Additional description for the firmware |
| version | string <= 255 characters Nullable A string that describes the version of the firmware |
Firmware was successfully created. Please note, that as long as there is no blob attached to the firmware not all fields in the response are set.
Your request could not be processed. This could e.g. mean that the provided JSON is not valid and cannot be parsed or that the object submitted to a POST or PATCH request failed to validate against JSON schema.
Your request is not authorized. This response means that you are not authorized to get access to the requested resource.
This response means you either do not have access to a specified resource or it does not even exist. The difference will not be exposed to the user to make iterating that much harder.
Internal Server Error response.
Production Environment
This endpoint returns a list with all available firmwares, ordered by creation date from newest to oldest.
| page | integer >= 0 Default: 0 The number of the result page starting with 0 |
| pageSize | integer >= 1 Default: 20 The number of items per page |
OK
Your request is not authorized. This response means that you are not authorized to get access to the requested resource.
This response means you either do not have access to a specified resource or it does not even exist. The difference will not be exposed to the user to make iterating that much harder.
Internal Server Error response.
Production Environment
This endpoint returns a firmware for the specified UUID.
| id required | string <uuid> The firmware ID |
OK
Your request is not authorized. This response means that you are not authorized to get access to the requested resource.
This response means you either do not have access to a specified resource or it does not even exist. The difference will not be exposed to the user to make iterating that much harder.
Internal Server Error response.
Production Environment
This endpoint allows the deletion of a firmware. All blob data associated with this firmware will also be deleted.
| id required | string <uuid> The firmware ID |
Firmware successfully deleted.
Your request is not authorized. This response means that you are not authorized to get access to the requested resource.
This response means you either do not have access to a specified resource or it does not even exist. The difference will not be exposed to the user to make iterating that much harder.
Internal Server Error response.
Production Environment
This endpoind allows the attaching of a blob to the specified firmware. Blob data can be a binary firmware file, configuration file or any other binary data is accepted. When a blob is attached to a firmware, a download link for the blob is added to the firmware resource which can be used to download the blob. Please note, that it's only allowed to attach a blob once. In case a blob is attached more than once you will get a 423 status code indicating that the resource is locked.
| id required | string <uuid> The firmware ID |
The blob data. Can be any arbitrary binary data.
Binary data
OK - Blob was successfully attached to the firmware.
Your request could not be processed. This could e.g. mean that the provided JSON is not valid and cannot be parsed or that the object submitted to a POST or PATCH request failed to validate against JSON schema.
Your request is not authorized. This response means that you are not authorized to get access to the requested resource.
This response means you either do not have access to a specified resource or it does not even exist. The difference will not be exposed to the user to make iterating that much harder.
A blob is already attached to the firmware and it's locked. Which means that the blob cannot be changed or replaced with a new blob.
Internal Server Error response.
Production Environment
This endpoint allows you to dowload an attached blob.
| id required | string <uuid> The firmware ID |
302 response
Your request could not be processed. This could e.g. mean that the provided JSON is not valid and cannot be parsed or that the object submitted to a POST or PATCH request failed to validate against JSON schema.
Your request is not authorized. This response means that you are not authorized to get access to the requested resource.
This response means you either do not have access to a specified resource or it does not even exist. The difference will not be exposed to the user to make iterating that much harder.
Internal Server Error response.
Production Environment
This endpoint creates a new firmware installation resource. This resource represents the status of installation into the slot for the specific device. Once it created, the device start receives installation instructions via MQTT.
| deviceId required | string <uuid> The device ID |
Firmware installation to add to the system.
| firmwareId required | string <uuid> The UUID of the firmware. |
| slot required | string <= 255 characters ^([a-zA-Z0-9_]+)$ The name of the slot for firmware installation. |
Firmware installation was successfully created.
Your request could not be processed. This could e.g. mean that the provided JSON is not valid and cannot be parsed or that the object submitted to a POST or PATCH request failed to validate against JSON schema.
Your request is not authorized. This response means that you are not authorized to get access to the requested resource.
This response means you either do not have access to a specified resource or it does not even exist. The difference will not be exposed to the user to make iterating that much harder.
Internal Server Error response.
Production Environment
This endpoint returns a list of firmware installations for a device.
| deviceId required | string <uuid> The device ID |
| latestOnly | boolean Default: false The flag that allows returning only the latest successful installation per slot |
OK
Your request is not authorized. This response means that you are not authorized to get access to the requested resource.
This response means you either do not have access to a specified resource or it does not even exist. The difference will not be exposed to the user to make iterating that much harder.
Internal Server Error response.
Production Environment
This endpoint returns a firmware-installation for the specified UUID.
| deviceId required | string <uuid> The device ID |
| installationId required | string <uuid> The firmware installation ID |
OK
Your request is not authorized. This response means that you are not authorized to get access to the requested resource.
This response means you either do not have access to a specified resource or it does not even exist. The difference will not be exposed to the user to make iterating that much harder.
Internal Server Error response.
Production Environment
This endpoint enables updating the status of firmware installation for a device. This installation status is tracking on the cloud side. Used by devices/gateways/analytics/etc which report statuses of the installation firmware into the slot.
| deviceId required | string <uuid> The device ID |
| installationId required | string <uuid> The firmware installation ID |
| startedAt required | string <date-time> The date when the firmware installation was started on device-side |
| completedAt | string <date-time> The date when the firmware installation was successfully completed on device-side |
| rejectedAt | string <date-time> The date when the firmware installation was rejected on device-side, due to some error |
| rejectReason | string <= 255 characters The description of firmware installation rejection |
OK
Your request is not authorized. This response means that you are not authorized to get access to the requested resource.
This response means you either do not have access to a specified resource or it does not even exist. The difference will not be exposed to the user to make iterating that much harder.
Internal Server Error response.
Production Environment
Events can be reported by devices. Typical event could be temperatureHigh or maintainanceNeeded. Events differ from reported data by typically being triggered by reaching a threshold or an event in the Device’s environment. In a future version of the Lightelligence Platform events can be used to trigger notifications etc.
Retrieve the events received inside last hour, latest first. Events can be filtered by their type. Note: This endpoint should only be used for debugging.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices uuid. |
| eventTypes | Array of strings Example: eventTypes=type1%2Ctype2%2Ctype3 A comma separated list of event types used as a filter. So only events with one of these types assigned will be returned. |
Success - the device's events.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
Internal Server Error response.
Production Environment
Send an event associated with a device. This endpoint can be used to emulate a real device sending events. The event type must be registered in the device type schema.
| type required | string <= 255 characters ^([a-zA-Z0-9_]+)$ The type of the event is used for filtering. Alphanumeric, may contain underscores. |
| value | object The reported event payload as an object. |
| createdAt | string <date-time> The date the event were created. If not included it will default to the system time at arrival. |
| deviceId required | string <uuid> The uuid of the device which emitted this event. |
| senderId | string <uuid> The uuid of the device which transmitted this event. |
Success - Event has been sent for processing.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
Internal Server Error response.
Production Environment
This endpoint creates a new firmware installation resource. This resource represents the status of installation into the slot for the specific device. Once it created, the device start receives installation instructions via MQTT.
| deviceId required | string <uuid> The device ID |
Firmware installation to add to the system.
| firmwareId required | string <uuid> The UUID of the firmware. |
| slot required | string <= 255 characters ^([a-zA-Z0-9_]+)$ The name of the slot for firmware installation. |
Firmware installation was successfully created.
Your request could not be processed. This could e.g. mean that the provided JSON is not valid and cannot be parsed or that the object submitted to a POST or PATCH request failed to validate against JSON schema.
Your request is not authorized. This response means that you are not authorized to get access to the requested resource.
This response means you either do not have access to a specified resource or it does not even exist. The difference will not be exposed to the user to make iterating that much harder.
Internal Server Error response.
Production Environment
This endpoint returns a list of firmware installations for a device.
| deviceId required | string <uuid> The device ID |
| latestOnly | boolean Default: false The flag that allows returning only the latest successful installation per slot |
OK
Your request is not authorized. This response means that you are not authorized to get access to the requested resource.
This response means you either do not have access to a specified resource or it does not even exist. The difference will not be exposed to the user to make iterating that much harder.
Internal Server Error response.
Production Environment
This endpoint returns a firmware-installation for the specified UUID.
| deviceId required | string <uuid> The device ID |
| installationId required | string <uuid> The firmware installation ID |
OK
Your request is not authorized. This response means that you are not authorized to get access to the requested resource.
This response means you either do not have access to a specified resource or it does not even exist. The difference will not be exposed to the user to make iterating that much harder.
Internal Server Error response.
Production Environment
This endpoint enables updating the status of firmware installation for a device. This installation status is tracking on the cloud side. Used by devices/gateways/analytics/etc which report statuses of the installation firmware into the slot.
| deviceId required | string <uuid> The device ID |
| installationId required | string <uuid> The firmware installation ID |
| startedAt required | string <date-time> The date when the firmware installation was started on device-side |
| completedAt | string <date-time> The date when the firmware installation was successfully completed on device-side |
| rejectedAt | string <date-time> The date when the firmware installation was rejected on device-side, due to some error |
| rejectReason | string <= 255 characters The description of firmware installation rejection |
OK
Your request is not authorized. This response means that you are not authorized to get access to the requested resource.
This response means you either do not have access to a specified resource or it does not even exist. The difference will not be exposed to the user to make iterating that much harder.
Internal Server Error response.
Production Environment
The timeseries data enables the developer to get the data reported by a Device over time. For data to show up in the timeseries data a reportingRule in the Device Type of a Device with the value timeseries is needed.
Get aggregated timeseries data for the device with the given UUID. Data will be returned in descending order. Maximum 4000 data points are returned.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices uuid. |
| startTime required | string <date-time> The start time of the time frame to request. |
| endTime required | string <date-time> The end time of the time frame to request. |
| frameSize | string Enum: "1m" "5m" "30m" "1h" "1d" The time frame size in which the values should be aggregated. By default, no frameSize is set and the data is not grouped by time. This means that the response contains exactly one result. In case frameSize is set and the number of points in the response exceed 4000, an error (400) will be returned. |
| aggregation required | string Enum: "min" "max" "mean" "sum" "count" "diff" "first" "last" Example: aggregation=max How should the values be aggregated. Supported values: min, max, mean, sum, count, diff, first, last. |
| path required | string Example: path=%24.attributes.sensor.brightness Path matching to a path defined in the reporting rules of the device's type. (e.g. |
Success - data.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
Internal Server Error response.
Production Environment
Get timeseries data for the last hour, as reported by the device with the given UUID. Data will be returned in an descending order. Maximum 4000 data points are returned. Note: This endpoint should be used by the user only for debugging his devices and the data they send.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices uuid. |
| path required | string Example: path=%24.attributes.sensor.brightness Path matching to a path defined in the reporting rules of the device's type. (e.g. |
Success - sensordata.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
Internal Server Error response.
Production Environment
Delete reported timeseries data of a device belonging to the given UUID. This deletes both the timeseries and its aggregation. If no timeframe is provided, all data for the device and path is deleted.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices uuid. |
| path required | string Example: path=%24.attributes.sensor.brightness Path matching to a path defined in the reporting rules of the device's type. (e.g. |
| startTime | string <date-time> The start time of the time frame to request. (RFC 3339) |
| endTime | string <date-time> The end time of the time frame to request. (RFC 3339) |
Success.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
Internal Server Error response.
Production Environment
Create a new timeseries dump, as reported by the device with the given UUID. The dump will be created asynchronously, and once completed will be available in the URL returned by this route. If no start and end time are specified, the dump contains all available data.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices uuid. |
| path required | string Path matching to a path defined in the reporting rules of the device's type. (e.g. |
| startTime | string <date-time> The dump contains data starting with the start time (RFC 3339) |
| endTime | string <date-time> The dump contains data starting till to the end time (RFC 3339) |
Success
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
Internal Server Error response.
Production Environment
Return a timeseries dump created asynchronously via a POST request. If the dump is not yet ready, this route will respond with a 404. All created dumps will expire after one hour.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The devices uuid. |
| dumpId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The UUID of the dump |
A JSON file
Bad Request response.
Unauthorized response.
Forbidden response.
Dump not found
Internal Server Error response.
Production Environment
Create a new dump of selected timeseries data. The dump will be created asynchronously, and once completed will be available in the URL returned by this route.
| dataFilter required | object |
| deviceFilter required | object Criteria for filtering data by device. If multiple filters of different types (for example, tags and aliases) are provided, the devices must match each of them. You need to provide at least one device filter. |
Success
Bad Request response.
Unauthorized response.
This response means you either do not have access to a specified resource or it does not even exist. The difference will not be exposed to the user to make iterating that much harder.
Internal Server Error response.
Production Environment
Return a timeseries dump created asynchronously via a POST request. If the dump is not yet ready, this route will respond with a 404. All created dumps will expire after one hour.
| dumpId required | string <uuid> Example: 07aba39a-ccb3-426f-838e-6d9a9ae330f4 The UUID of the dump |
A JSON file
Bad Request response.
Unauthorized response.
This response means you either do not have access to a specified resource or it does not even exist. The difference will not be exposed to the user to make iterating that much harder.
Dump not found
Internal Server Error response.
Production Environment
Get aggregated timeseries data points for the devices matching the given filters. The data dump will be created asynchronously, and once completed will be available at the URL returned by this route. Data points in the dump will be sorted chronologically from newest to oldest.
| dataFilter required | object |
| params required | object |
| deviceFilter required | object Criteria for filtering data by device. If multiple filters of different types (for example, tags and aliases) are provided, the devices must match each of them. You need to provide at least one device filter. |
Request accepted
Bad Request response.
Unauthorized response.
This response means you either do not have access to a specified resource or it does not even exist. The difference will not be exposed to the user to make iterating that much harder.
Internal Server Error response.
Production Environment
Return an aggregated timeseries data dump created asynchronously via a POST request. If the dump is not yet ready, this route will respond with a 404. All created dumps will expire after one hour. Data points in the dump will be sorted chronologically from newest to oldest.
| dumpId required | string <uuid> Example: 07aba39a-ccb3-426f-838e-6d9a9ae330f4 The UUID of the dump |
A JSON file
Bad Request response.
Unauthorized response.
This response means you either do not have access to a specified resource or it does not even exist. The difference will not be exposed to the user to make iterating that much harder.
Dump not found
Internal Server Error response.
Production Environment
Create timeseries for tenant
| name required | string Name of the timeseries |
| dataType required | object JSON schema of timeseries data points. |
| metadata | object List of key-value attached to timeseries |
Success - timeseries added.
Bad Request response.
Unauthorized response.
Access forbidden.
Internal Server Error response.
Production Environment
Get list of available timeseries, ordered by created date descending.
| page | integer >= 0 Default: 0 The number of the result page starting with 0. |
| pageSize | integer >= 0 Default: 20 The number of result per page. |
| timeseriesIds | Array of strings <uuid> non-empty Filter timeseries by id (OR filter). |
| metadata | object List of key-value attached to timeseries |
OK
Bad Request response.
Unauthorized response.
Access forbidden.
Internal Server Error response.
Production Environment
Get a specific timeseries type by UUID
| timeseriesId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The timeseries UUID. |
Success - requested timeseries.
Bad Request response.
Unauthorized response.
Access forbidden.
Resounce not found.
Internal Server Error response.
Production Environment
Edit a specific timeseries by UUID partially. UUID is not patchable.
| timeseriesId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The timeseries UUID. |
| name | string Name of the timeseries |
| dataType | object JSON schema of timeseries data points. |
| metadata | object List of key-value attached to timeseries |
Success - edited timeseries.
Bad Request response.
Unauthorized response.
Access forbidden.
Resounce not found.
Internal Server Error response.
Production Environment
Delete a specific timeseries by UUID.
| timeseriesId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The timeseries UUID. |
Success - deleted timeseries.
Bad Request response.
Unauthorized response.
Access forbidden.
Resounce not found.
Internal Server Error response.
Production Environment
Create data points (one or more) for specific timeseries (ingest)
| timeseriesId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The timeseries UUID. |
| data required | Array of objects |
Success - timeseries data point added.
Bad Request response.
Unauthorized response.
Access forbidden.
Resounce not found.
Internal Server Error response.
Production Environment
Delete reported data points of a timeseries belonging to the given UUID. This deletes both the timeseries and its aggregation. If no timeframe is provided, all data is deleted.
| timeseriesId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The timeseries UUID. |
| startTime | string <date-time> The start time of the time frame to request. (RFC 3339) |
| endTime | string <date-time> The end time of the time frame to request. (RFC 3339) |
Success.
Bad Request response.
Unauthorized response.
Access forbidden.
Resounce not found.
Internal Server Error response.
Production Environment
Get data points for the last hour, as reported for the timeseries. Data will be returned in an descending order. Maximum 4000 data points are returned. NOTE: This endpoint should be used by the user only for debugging his timeseries.
| timeseriesId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The timeseries UUID. |
Success - timeseries data points.
Bad Request response.
Unauthorized response.
Access forbidden.
Resounce not found.
Internal Server Error response.
Production Environment
Get aggregated data points for the timeseries. Data will be returned in an descending order. Each page will contain at most 4000 entries, it might contain less entries if some of the time-frames from the interval did not have any data points.
| timeseriesId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The timeseries UUID. |
| startTime required | string <date-time> The start time of the time frame to request. |
| endTime required | string <date-time> The end time of the time frame to request. |
| frameSize | string Enum: "1m" "5m" "15m" "30m" "1h" "1d" The time frame size in which the values should be aggregated. By default, no frameSize is set and the data is not grouped by time - this means that the response contains exactly one result. |
| aggregation required | string Enum: "min" "max" "mean" "sum" "count" "diff" "first" "last" Example: aggregation=max How should the values be aggregated. Supported values: min, max, mean, sum, count, diff, first, last. |
| page | integer >= 0 Default: 0 The number of the result page starting with 0. |
| pageSize | integer >= 0 Default: 20 The number of result per page. |
Success - timeseries data points.
Bad Request response.
Unauthorized response.
Access forbidden.
Resounce not found.
Internal Server Error response.
Production Environment
Get aggregated data points for the timeseries matching the given filters. Data will be returned in descending order.
| dataFilter required | object Start time and end time filter of the requested timeseries. |
| timeseriesFilter required | object Filter for timeseries |
| params required | object |
Request accepted
Bad Request response.
Unauthorized response.
Access forbidden.
Resounce not found.
Internal Server Error response.
Production Environment
Request a file with raw data points, as reported by the timeseries matching the given filters.
| dataFilter required | object Start time and end time filter of the requested timeseries. |
| timeseriesFilter required | object Filter for timeseries |
Request accepted
Bad Request response.
Unauthorized response.
Access forbidden.
Resounce not found.
Internal Server Error response.
Production Environment
Return a status of a timeseries file that's being created asynchronously.
| requestId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The UUID of the request |
The file is still being created.
The file was created.
Bad Request response.
Unauthorized response.
Access forbidden.
Resounce not found.
Internal Server Error response.
Production Environment
Return a timeseries file created asynchronously via a POST request. All created files will expire 1 hour after they are created.
| fileId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The UUID of the file |
A JSON file
Bad Request response.
Unauthorized response.
Access forbidden.
Resounce not found.
Internal Server Error response.
Production Environment
The ingest endpoints are the HTTP equivalent to the platforms MQTT Endpoints, where Devices can report their data. These HTTP endpoints can be used to implement a quick proof of concept. We don’t recommend to use them in deployed Devices.
Send an event associated with a device. This endpoint can be used to emulate a real device sending events. The event type must be registered in the device type schema.
| type required | string <= 255 characters ^([a-zA-Z0-9_]+)$ The type of the event is used for filtering. Alphanumeric, may contain underscores. |
| value | object The reported event payload as an object. |
| createdAt | string <date-time> The date the event were created. If not included it will default to the system time at arrival. |
| deviceId required | string <uuid> The uuid of the device which emitted this event. |
| senderId | string <uuid> The uuid of the device which transmitted this event. |
Success - Event has been sent for processing.
Bad Request response.
Unauthorized response.
Forbidden response.
Not Found response.
Internal Server Error response.
Production Environment
Send data associated with a device. This endpoint can be used to emulate a real device sending data, or to import existing data sets. The payload must be compatible with the device type schema.
| senderId required | string <uuid> The UUID of the device that sends the data. If the device is sending it by itself, senderId equals deviceId; if the data for the device is sent to the cloud by a gateway, then the senderId is the id of the gateway; |
| deviceId required | string <uuid> The devices UUID the reported value belongs to. (This means, that this device Id maybe not matches the deviceId of the sending device). |
| type required | string Enum: "attributes" "configuration" Defines the type of the value object you report in the value property, to be able to decide if the reported value belongs to the configuration or the attributes of a device. |
| value required | object The reported Value as object. |
| time | string <date-time> See RFC 3339. If no time is provided, the time the message arrived at the endpoint is used. |
Success - Event has been sent for processing.
Bad Request response.
Unauthorized response.
Forbidden response.
Production Environment
Request a new WebSocket connection URL. If the request and authentication is successful the provided URL from the response can be used to establish a new WebSocket connection.
The stream capabilities depend on its type.
live stream: service starts streaming events once connection is established.
When client reconnects again, stream starts from the point of connection. Events that
happened when client was disconnected are dropped.
buffered stream: service starts buffering events once connected. Events streamed from the persistent storage,
so there is might be some latency comparing to live streams. Events stay in the buffer for 2 days.
It means if time between reconnections is shorter than 2 days, already consumed events can be deliverd again.
The age of events to deliver is specified by options.replayFromTimestamp parameter.
If the client wouldn't make any new connections longer than 2 days after last disconnect, the service will
stop buffering for the given client.
Note: The WebSocket connection URL is only valid for 15 seconds. If the url has expired, a new url needs to be requested.
| type | string Enum: "live" "buffered" Specify the type of streaming connection requested. Defaults to "live". Live connections instantly sends messages received to the WebSocket connection, whereas buffered connection starts buffering messages for tenant on first connection. If connection is lost, messages that are up to two days old can be replayed. |
| options | object Specify options for the streaming connection. Not necessary on first connection. |
| filter required | object Filter which allows to receive updates for specific message types and devices; The five filter conditions ("type", "deviceId", "tag", "attributes" and "configurations") are treated as an AND, the values provided in the arrays are treated as an OR. So the websocket client will receive all messages that contains ONE of the mentioned message types AND originates from ONE of the mentioned device ids. |
Success - A new WebSocket connection can be established with the provided WebSocket URL in the response.
Bad request
Unauthorized
Token is not valid
Internal Server Error
Production Environment
IMPORTANT NOTE: this path is likely to change, DO NOT RELY ON THE EXACT PATH, just take the URL that is returned from the POST as is.
time to order the messages received in the client.| token required | string <string> Example: bbdf5d13d9a09ab5cfe5c45536ecf4f432e9c4736aeb6d930ea240904d0ae7d8 The token used to authenticate the WebSocket connection |
Token is not valid
Internal Server Error
Production Environment
IMPORTANT NOTE: DO NOT RELY ON THE EXACT PATH, just take the URL that is returned from the POST as is.
time to order the messages received in the client.| token required | string <string> Example: bbdf5d13d9a09ab5cfe5c45536ecf4f432e9c4736aeb6d930ea240904d0ae7d8 The token used to authenticate the WebSocket connection |
| type required | string Enum: "live" "buffered" Example: live The streaming type |
Token is not valid
Internal Server Error
Production Environment
With the diagnostics endpoints it is possible to debug what Device’s messages (reported data, events) are doing in the cloud. As MQTT does not return error messages, this is the way to see what fails in the process.
Get diagnostics data for the last hour, as reported for the device with the given UUID. Device Diagnostics contain errors in handling the data from the device on the cloud side. Data will be returned in descending order.
| deviceId required | string <uuid> Example: 123e4567-e89b-12d3-a456-426655440000 The device to filter for (uuid) |
OK
Bad Request response.
Unauthorized response.
Not Found response.
Internal Server Error response.
Production Environment
Audit logs provide a detailed log on all relevant actions that users initiate via the OLT API.
Access available audit logs of your tenant.
When using a application/json mime type, audit logs with pagination will be returned.
When using the text/csv mime type, the content is a comma separated csv file, containing all available audit logs, where its first line are the column names. All properties which are available as json are also listed here in the csv.
| page | integer >= 0 Default: 0 The requested page |
| pageSize | integer [ 1 .. 100 ] Default: 20 The amount of results per page |
Success
Bad Request
Unauthorized
Forbidden
Internal Server Error
Production Environment