Skip to main content
API docs by Redocly

ESP RainMaker API Definitions for the Backend Service (2.8.1-5599f3ea2_2025-01-31T06:49)

Download OpenAPI specification:Download

E-mail: esp-rainmaker-admin@espressif.com License: Apache 2.0 Terms of Service

The API Defintions for the Rainmaker APIs.

It supports two types of APIs:

  • Unauthenticated
  • Authenticated (APIs having a lock symbol at the end)
    To use Authenticated APIs, an accesstoken must be passed manually in the Authorization header. This can be done by clicking on the Authorize button shown below and adding the accesstoken in the Value field. This accesstoken can be obtained by logging in using the /login2 API. (Not supported for social users for now)

Note:

  • No double slashes allowed in the URL.
  • Headers such as data, verify, and cookies are not supported.
Find out more about ESP RainMaker

API Versions

API to get information about supported API versions

Get supported API versions

This API returns information about the supported API versions

Responses

Response samples

Content type
application/json
{
  • "supported_versions": [
    ],
  • "additional_info": [
    ]
}

User Management

User Creation, Login, Authentication and Password management

Creates the new user or confirms the user. The user can specify his email address or the mobile number with country code for creating his account.

This API creates a new user or confirms the user. If the password is specified in the request body, a new user is created and a verification code is sent to user's mail address/phone number. If the verification code is sent in the request body, the user is confirmed.

path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

Request Body schema: application/json
required

Request body for creating new user or confirming the user

One of
user_name
string
password
string [ 8 .. 256 ]

Responses

Request samples

Content type
application/json
Example
{
  • "user_name": "username@domain.com or <+Mobile Number with country code>",
  • "password": "password"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "description": "Success description"
}

Updates Name and Phone number of the user

This API sets or updates the name or phone number of the user, amongother fields.

MFA can also be enabled / disabled for superadmins. If MFA is enabled, an SMS with verification code is sent to the superadmin's phone number after initial authentication for successful login.

Note:

  • The verification_code will confirm the current phone_number.
  • At any point there can be just one phone number associated with the user. Adding a new phone number will replace the existing one and require reverification.
  • The MFA settings will reflect from the next login onwards.

Users can also update the User Attribute Tags on themselves.
Note: User cannot detach the Attribute Tags which are added by Admins.

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

Request Body schema: application/json
required

Request body for updating name / phone number of the user

One of
name
string

Responses

Request samples

Content type
application/json
Example
{
  • "name": "new name"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "description": "Success description"
}

Fetches the details of current user

This API fetches user_id, user_name, super_admin flag, URL of profile picture and name of current user.

The super_admin flag is returned only when the user is a super admin, in other cases, it will not be returned in the output.
Also the picture_url and name are not returned in the output, if it is not set by the user.

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

query Parameters
custom_data
boolean
Default: false

When true, will fetch the custom data of the logged in user containing.

Responses

Response samples

Content type
application/json
Example
{
  • "user_id": "string",
  • "user_name": "string",
  • "super_admin": true,
  • "picture_url": "string",
  • "name": "string",
  • "mfa": true,
  • "phone_number": "<+Mobile Number with country code>"
}

Deletes user account

This API can be used by end-users to delete his/her account. Here are the details-

  • If the 'request' query param is true, user delete request is initiated and verification code is sent to user using email or phone number.
  • If 'verification_code' query param is specified, user account is deleted.

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

query Parameters
request
boolean
Default: false

if delete user request is to be initiated, value of request param should be true.

verification_code
number
Default: "<verification_code>"

if delete user request is to be verified and user account is to be deleted, the verification code received by user should be entered as value of verification_code query param.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "description": "Success description"
}

Handle login or extend session request from the user

This API will be used by the users to Login to RainMaker or to extend an existing session
If MFA is enabled, then an SMS will be sent to the phone number after authentication with password. Then, verifying the code and session will lead to successful login of the user.

path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

Request Body schema: application/json
required

username and password for Login

One of
user_name
string
password
string [ 8 .. 256 ]

Responses

Request samples

Content type
application/json
Example
{
  • "user_name": "username@domain.com or +Mobile Number with country code",
  • "password": "password"
}

Response samples

Content type
application/json
Example
{
  • "status": "success",
  • "description": "Login successful",
  • "idtoken": "idtoken",
  • "accesstoken": "accesstoken",
  • "refreshtoken": "refreshtoken"
}

Log out user from the session

This API will be used by the users to Logout from Rainmaker session. If optionally refreshtoken is provided, the token is revoked.

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

query Parameters
logout_all
string
Default: "false"

Using this flag the user can be logged out from all sessions or only current session. The possible values are true and false.

Request Body schema: application/json
One of
refreshtoken
string

Responses

Request samples

Content type
application/json
{
  • "refreshtoken": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "description": "Success description"
}

Handle password change request from the user

This api handles change password request from the user. Please note, this logs out all the existing sessions of the user.

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

Request Body schema: application/json
required

Password change request parameters

password
string [ 8 .. 256 ]
newpassword
string [ 8 .. 256 ]

Responses

Request samples

Content type
application/json
{
  • "password": "password",
  • "newpassword": "newpassword"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "description": "Success description"
}

Handle forgot password request from the user

This api handles forgot password request from the user. Please note, this does not log out the existing sessions of the user.

path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

Request Body schema: application/json
required

password change request parameters

One of
user_name
string

Responses

Request samples

Content type
application/json
Example
{
  • "user_name": "username@domain.com or +Mobile Number with country code"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "description": "Success description"
}

User Node Association

Associating a node with the user

Get the nodes associated with the user

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

query Parameters
node_id
string
Example: node_id=node_id1

node Id of node to get the node details

node_details
boolean
Default: false

optional flag (true/false), to indicate if the node details are required in the response

status
boolean
Default: true

optional flag (true/false), to indicate if the node details should contain status in the response or not.

config
boolean
Default: true

optional flag (true/false), to indicate if the node details should contain config in the response or not.

params
boolean
Default: true

optional flag (true/false), to indicate if the node details should contain params in the response or not.

start_id
string

use next_id from the response as start_id to fetch the next set of records

num_records
string

number of nodes to fetch

tags
string
Example: tags=location:pune OR location:bangalore

Used to fetch list of nodes based on tags.

show_tags
boolean
Default: true

optional flag (true/false), to indicate if the node details should contain tags in the response or not.

is_matter
boolean
Default: false

optional flag (true/false), If the is_matter flag is given, user will get matter nodes list.

Responses

Response samples

Content type
application/json
{
  • "nodes": "[ nodeid1, ... ]",
  • "node_details": [
    ],
  • "next_id": "nodeid1",
  • "total": 5
}

Add tags to Node or update the metadata

This api is used to attach tags to Node or update the metadata, or grant node access to admins.

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

query Parameters
node_id
required
string

Used to specify nodeId

Request Body schema: application/json
optional

Request body for attaching tags or updating metadata of the node.
Can also grant access of node data like config and params to admins.
metadata -> This is a custom metadata which follows thingshadow JSON rules

  1. 1.metadata -> null The metadata will get deleted entirely
  2. 2. metadata -> {} There will be no change in the metadata also no validation error in the input
  3. 3. metadata -> object of key and value where key will be string and value can be any data type(array, object, string, number , boolean) Metadata will get stored in the above format , new keys will get appended and the existing keys value will get updated accordingly
  4. 4. metadata -> {“key”:null} Metadata JSON keys can be deleted by above syntax
  5. 5. If value is array, it will get overwrite and not update


Matter fabric

tags
Array of strings
metadata
object
grant_admin_access
string
Enum: "READ" "WRITE" "NONE"

Responses

Request samples

Content type
application/json
Example
{
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "description": "Success description"
}

Delete tags from Node

This api is used to remove tags from Node

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

query Parameters
node_id
required
string

Used to specify nodeId

Request Body schema: application/json
required

Request body for removing tags with the node.

tags
Array of strings

Responses

Request samples

Content type
application/json
{
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "description": "Success description"
}

Get the configuration for the node

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

query Parameters
node_id
required
string

node id

Responses

Response samples

Content type
application/json
{
  • "node_id": "nodeid1",
  • "config_version": "config_version",
  • "devices": [
    ],
  • "info": {
    }
}

Add or Remove the User Node mapping

  • You can optionally specify tags and metadata.
  • Group ID can be specified to provide the functionality of adding a node to the group.
  • Nodes can be searched by tags.
  • If tags are not provided in the request, and esp.location is present in the user's custom_data, then all the keys starting with esp under it are converted to tags.


    • Note: If all the mappings of a node are removed or if the node is mapped with `reset:true` then the time-series data associated with that node will also be deleted.
Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

Request Body schema: application/json
required

Add or Remove User Node Mapping Request Parameters

node_id
string [ 12 .. 36 ]
secret_key
string >= 1
operation
string
Enum: "add" "remove"

operation can be add or remove

tags
Array of strings
metadata
object
group_id
string

group_id is used to add the node which is getting mapped to this group

Responses

Request samples

Content type
application/json
Example
{
  • "node_id": "node_id",
  • "secret_key": "secret_key",
  • "operation": "add"
}

Response samples

Content type
application/json
Example
{
  • "status": "success",
  • "description": "Success description",
  • "request_id": "request_id"
}

Get the status of User Node mapping request

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

query Parameters
request_id
required
string

request Id

Responses

Response samples

Content type
application/json
{
  • "request_status": "confirmed"
}

Add the request to add User Node mapping based on challenge_response

The API is the first step in challenge-based user node mapping. This API generates a random string(challenge) and request ID. The returned challenge needs to be signed with device key and given at the verify step of the mapping.

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

Request Body schema: application/json
required

Initiate challenge-based User Node Mapping Request

timeout
number

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "status": "success",
  • "description": "Success description",
  • "request_id": "request_id"
}

Verify the challenge-based user node mapping request

This API is second step in challenge-based user node mapping. This API verifies the challenge_response value and adds the user node mapping if the challenge_response value is valid.

  • You can optionally specify tags and metadata.
  • Nodes can be searched by tags.
  • If tags are not provided in the request, and esp.location is present in the user's custom_data, then all the keys starting with esp under it are converted to tags.
  • Group ID can be specified to provide the functionality of adding a node to the group.

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

Request Body schema: application/json
required

Verify User Node Mapping Request Parameters

request_id
required
string
challenge_response
required
string
node_id
string [ 12 .. 36 ]
tags
Array of strings
metadata
object
group_id
string

group_id is used to add the node which is getting mapped to this

Responses

Request samples

Content type
application/json
Example
{
  • "request_id": "request_id",
  • "challenge_response": "challenge_response"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "description": "Success description"
}

This API creates the sharing of Nodes between users.

This API allows

  1. Primary users to share the nodes with other users either with primary user role or secondary. User Name of the requested user and nodes are mandatory parameters. Primary flag for adding user with primary role is an optional parameter.Metadata is an optional parameter, used to store an additional info about node sharing request.
  2. Requested user can accept or decline the request for node sharing sent by the primary users. Here accept and request_id are mandatory parameters

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

Request Body schema: application/json
required

Add User Node Sharing / Accept or Decline Sharing Request Parameters

One of
node_ids
required
Array of strings
user_name
required
string
primary
boolean
metadata
object
transfer
boolean
new_role
string

Responses

Request samples

Content type
application/json
Example
{
  • "nodes": [
    ],
  • "user_name": "username@domain.com",
  • "primary": true,
  • "metadata": {
    }
}

Response samples

Content type
application/json
Example
{
  • "status": "success",
  • "description": "Success description",
  • "request_id": "request_id"
}

This API removes the sharing of Nodes between the users.

This API allows the primary users to remove the sharing of nodes with other users.

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

query Parameters
nodes
required
string

Comma separated nodeids (Example nodes=nodeid1,nodeid2)

user_name
required
string
Example: user_name=username@domain.com

User Name

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "description": "Success description"
}

This API fetches the sharing details for the nodes the current user is associated with.

This API is used to fetch the Node sharing details. Here are the details -

  • When no parameters are passed it returns the sharing details of all the nodes that this user is associated with (Primary or Secondary)
  • When node_id is passed, it returns the sharing details of that node. The requesting user can be Primary or Secondary.
  • If this API is called by the secondary user, the list of other secondary users this node is associated with, is not returned but the sources from where this node was shared will be returned.
    • When NODE is present in the sources array it represents that it was shared via Node sharing
    • Else it was shared via Group sharing and the list will have group Ids

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

query Parameters
node_id
string

node Id of node to get the sharing details

Responses

Response samples

Content type
application/json
Example
{
  • "node_sharing": [
    ]
}

This API is used to get the sharing requests raised between users.

This API allows the primary and secondary users to get the sharing requests.

  1. To get the requests raised by primary user, with primary_user flag set as true
  2. To get the requests received by secondary user
  3. To get the details of a request by request_id
To support pagination start_request_id, start_user_name, num_records are added to the API.

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

query Parameters
request_id
string

request Id

primary_user
string

This is a boolean flag, which is used to denote whether to get the requests raised by Primary user(true) or received by secondary users (false). Default value for this flag is false.

start_request_id
string

used in pagination

start_user_name
string

used in pagination along with start_request_id

num_records
string

used to specify the no of records that must be returned. Default value is 10. The valid values are in the range of 1 to 10. If invalid value is given, default value is used.

Responses

Response samples

Content type
application/json
{
  • "sharing_requests": [
    ]
}

This API removes the sharing request of Nodes between the users.

This API allows the primary users to remove the sharing request of nodes with other users.

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

query Parameters
request_id
required
string

Request Id

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "description": "Success description"
}

This API creates the sharing of Nodes between users.

This API allows

  1. Primary users to share the nodes with other users either with primary user role or secondary. User Name of the requested user and nodes are mandatory parameters. Primary flag for adding user with primary role is an optional parameter.Metadata is an optional parameter, used to store additional info about node sharing request.
  2. Requested user can accept or decline the request for node sharing sent by the primary users. Here accept and request_id are mandatory parameters

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

Request Body schema: application/json
required

Add User Node Sharing / Accept or Decline Sharing Request Parameters

One of
node_ids
required
Array of strings
user_name
required
string
primary
boolean
metadata
object
transfer
boolean
new_role
string

Responses

Request samples

Content type
application/json
Example
{
  • "nodes": [
    ],
  • "user_name": "username@domain.com",
  • "primary": true,
  • "metadata": {
    }
}

Response samples

Content type
application/json
Example
{
  • "status": "success",
  • "description": "Success description",
  • "request_id": "request_id"
}

Get the online or offline status for the node

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

query Parameters
node_id
required
string

node id

Responses

Response samples

Content type
application/json
{
  • "connectivity": {
    }
}

Get the nodes claimed by the Admin user

This API is to get the node details of nodes claimed by the admin:

  • When no parameter is passed list of all the nodes and nodeInfo are returned.
  • When type is passed, list of all the nodes and nodeInfo which are of that type are returned.
  • When model & type is passed, list of all the nodes and nodeInfo which are of that model & type are returned.
    • Note: type is a required parameter if model is provided.
  • When model, type & fw_version is passed, list of all the nodes and nodeInfo which are of that model, type & fw_version are returned.
    • Note: model & type is a required parameter if fw_version is provided.
  • When subtype is passed, list of all the nodes and nodeInfo which are of that subtype are returned.
  • When project_name is passed, list of all the nodes and nodeInfo which are of that project_name are returned.
  • When subtype and project_name is passed, list of all the nodes and nodeInfo which are of that subtype & project_name are returned.
  • We can use type along with subtype, project_name, model and fw_version
  • When node status is passed, list of all the nodes and nodeInfo that have the given status are returned.
    • Node status can also be provided in conjunction with tags, type, model & fw_version, subtype & project_name
  • When node_id is passed the details of that node (NodeInfo) is returned

    • To support pagination num_records and start_id are present

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    num_records
    string

    Used for pagination, number of records to be fetched

    start_id
    string

    Used for pagination, Start Id of the record to be fetched

    node_id
    string

    Used to fetch details of particular node

    type
    string
    Example: type=led

    Used to fetch list of nodes based on type.

    model
    string
    Example: model=2021

    Used to fetch list of nodes based on model and type.

    fw_version
    string
    Example: fw_version=1.0

    Used to fetch list of nodes based on model, type & fw_version.

    tags
    string
    Example: tags=location:pune OR location:bangalore

    Used to fetch list of nodes based on tags.

    node_status
    string
    Example: node_status=online

    Used to fetch list of nodes based on node status. They can be not_activated, online, offline, deactivated, active and inactive.

    not_activated: node hasn't connected even once to the cloud
    online: node is connected
    offline: node is not connected
    deactivated: the node certificate is deactivated

    subtype
    string
    Example: subtype=LED bulb

    Used to fetch list of nodes based on subtype.

    project_name
    string
    Example: project_name=rainmaker

    Used to fetch list of nodes based on project_name.

    summary
    boolean
    Example: summary=true

    Used to fetch node count summary of active, inactive and non activated nodes. start_time should also be provided.

    start_time
    number
    Example: start_time=1683110219659

    Used only if summary is true. This is the time window till the current time for which the node came online atleast once and was hence active.

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "nodes": [
      ],
    • "node_info": [
      ],
    • "next_id": "thing2",
    • "total": 123,
    • "quota": 5
    }

    Node Operations

    This api is used to activate/deactivate Node certificates or attach tags to nodes.
    To Activate/Deactivate node certificates, use query parameters node_id and activate with value as true for activation and false to deactivate the certificate.
    To Attach the tags to nodes, specify tags in the request body. Refer the example Attach tags

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    activate
    boolean

    Used for specifying either to activate the nodes or deactivate the nodes

    node_id
    required
    string

    Used to specify nodeId. Multiple NodeId values have to be comma-separated. Maximum 25 nodeIds supported.

    Request Body schema: application/json
    optional

    Request body for attaching tags with the nodes.

    tags
    Array of strings

    Responses

    Request samples

    Content type
    application/json
    {
    • "tags": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Remove tags from node

    This api is used to remove tags

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    node_id
    required
    string

    Used to specify nodeId

    Request Body schema: application/json
    required

    Request body for attaching tags with the node.

    tags
    Array of strings

    Responses

    Request samples

    Content type
    application/json
    {
    • "tags": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Get the Tag Names of all the nodes claimed so far

    This API is used to get the list of Tag Names or Tag Values mapped to the Tag Names

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    num_records
    string

    Used for pagination, number of records to be fetched

    start_id
    string

    Used for pagination, Start Id of the record to be fetched

    tag_name
    string

    Used to find tag values associated with the particular tag name

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "tags": [
      ],
    • "next_id": "location",
    • "total": 5
    }

    Get the user node association

    This API is accessible to superadmins. When a user_id is provided, it fetches the nodes associated with the user, and when a node_id is provided, it fetches the user associated with the node.
    If the role is specified as a query parameter (primary or secondary), it returns the users or nodes with that role.
    To get node details, set the node_details flag to true.

    Note:

    • If both user ID and user name are provided simultaneously, the user ID will take priority, and nodes will be fetched according to the user ID.
    • If user ID and node ID, or user name and node ID, are specified at the same time, the API will return an error.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    user_id
    string

    user_id of the user whose nodes are to be fetched.

    user_name
    string

    email or phone number of the user whose nodes are to be fetched, whatever user has used to sign up. Example - username@domain.com or +

    node_id
    string

    node_id of the node whose associated users are to be fetched.

    role
    string

    the nodes associated with the user returned will have this specified role. Default - both primary and secondary

    node_details
    boolean
    Default: false

    optional flag (true/false), to indicate if the node details are required in the response

    start_id
    string

    use next_id from the response as start_id to fetch the next set of records

    num_records
    string

    number of nodes to fetch

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "primary": {
      },
    • "secondary": {
      },
    • "total": 4,
    • "next_id": "node_id3"
    }

    Node Parameter Operations

    Update the state of the node or get the state of the node

    Update the Node Parameter

    This API will update the state of the device

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    node_id
    string

    node id

    Request Body schema: application/json
    required

    Request body for updating Node Parameter

    One of
    object
    object

    Responses

    Request samples

    Content type
    application/json
    Example
    [
    • {
      }
    ]

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Get the Node parameter

    This API will Get the state of the device

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    node_id
    required
    string

    node id

    Responses

    Response samples

    Content type
    application/json
    {
    • "Light": {
      },
    • "Switch": {
      }
    }

    OTA Service

    APIs to upload Firmware images and manage OTA jobs

    This API is used for uploading a new Firmware image

    This API uploads the new Firmware image to Rainmaker Cloud.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for uploading new firmware image. List of optional parameters

    • fw_version
    • model
    • type

    These above parameters will be fetched from base64_fwimage when not passed in request body.
    If absent in both places then error will be returned.

    fw_version
    string
    image_name
    required
    string
    model
    string
    type
    string
    base64_fwimage
    required
    string

    Responses

    Request samples

    Content type
    application/json
    {
    • "fw_version": "1.0",
    • "image_name": "Alexa echo 2",
    • "model": "echo 2",
    • "type": "alexa",
    • "base64_fwimage": "base 64 encoded image string"
    }

    Response samples

    Content type
    application/json
    {
    • "ota_image_id": "string",
    • "image_url": "string",
    • "status": "string"
    }

    Get the details about OTA images for the user

    This API gives the details about the OTA image. If the ota_image_id or the ota_image_name is not specified, all the images for the user are returned.

  • If contains flag is set to true, pattern search will be applied on image_name specified.

    • Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    ota_image_id
    string

    OTA Image Id

    image_name
    string

    OTA Image Name

    type
    string

    OTA Image Type

    model
    string

    OTA Image Model

    num_records
    string

    Used for pagination, number of records to be fetched

    start_id
    string

    Used for pagination, Start Id of the record to be fetched

    contains
    boolean
    Default: false

    For pattern search on image_name

    archived
    boolean
    Default: false

    If set to true, will return only archived OTA images

    all
    boolean
    Default: false

    If set to true, will return all images irrespective of archived status

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "ota_images": [
      ],
    • "total": "total records available",
    • "next_id": "id of the next record"
    }

    Delete the OTA Image for the user

    This API deletes the OTA image for the user, if it is not used in any of the OTA jobs. If the OTA image is used in any of the OTA jobs, an error is returned.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    ota_image_id
    required
    string

    OTA Image Id

    force_delete
    string
    Default: "false"

    Delete the OTA Image forcefully (Even if it is associated with any cancelled OTA Job)

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Archive/Unarchive an OTA image

    This API archives/unarchives the OTA image for the user

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    ota_image_id
    required
    string

    OTA image id

    archive
    required
    boolean

    Archives the image when true and unarchives the image when false

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Get pre-signed url to upload the firmware image or firmware package zip to S3

    This API is used to fetch presigned upload_url (Validity: 1 hour) to upload the firmware image or firmware package file.

    Supported image types are package for uploading zip file containing OTA image, bootloader and other related files) and firmware for uploading OTA image binary file.

    Default image_type is firmware, if image_type is not specified.

    The user needs to specify the OTA image_name. Image name is the name of OTA image binary. This image_name is independent of the firmware image binary/ firmware package file name.

    For image_type=package, please provide image_name as name of the zip file that you are uploading, without the .zip extension. The file name must be of format your-project-name_version.zip.

    To verify the integrity of the file uploaded to s3, the user can provide an optional md5 checksum only as per the instructions in the params md5_checksum below.

    Note:

    • If already existing OTA image_name is given and the OTA image is not referenced by any OTA job, it will be replaced. This action cannot be undone.
    • The client will have to send a PUT HTTP request to the upload_url with headers -
      'Content-type': 'application/octet-stream'
    • If md5 checksum was added during GET call then the same has to added as an header in the PUT api for upload with headers -
      'Content-MD5': 'correct/valid_md5checksum_of_uploaded_file/image'
    • The value of the Content-MD5 header has to be in the base64 format only. No replacement of symbols like '+' with %2b. Add the md5 checksum in base64 as it is.
    • If upload_url is expired you will get a 403 Forbidden response. You may fetch a new upload_url.
    • Maximum supported OTA Image size is 200 MB. For OTA package file(image_type=package), there is no limit on package file size, but binary file inside uploaded zip must be upto 200 MB in size.
    • Nodes won't be able to download the OTA images with size more than 24 MB via MQTT streams i.e. MQTT based file delivery won't be available.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    image_name
    required
    string

    Name of the OTA firmware image to be uploaded

    image_type
    string
    Default: "firmware"

    Image type(firmware/package/raw).

    md5_checksum
    string

    It should be a valid/correct MD5 checksum of the file. It should be in base64 format only. If there are any '+' symbols in the checksum, then they should be replaced by '%2b' while adding as the param value in the GET request.

    Responses

    Response samples

    Content type
    application/json
    {
    • "ota_image_id": "<ota_image_id>",
    • "upload_url": "url",
    • "status": "success"
    }

    This API is used to confirm the upload Firmware image or package.

    After the admin uploads the image(firmware/package zip) to S3 bucket, this API needs to be called.

    It is expected that the admin will upload the files separately using a suitable tool with the help of the pre-signed upload URL returned by the GET: /admin/otaimage/upload_request.

    Supported values for image_type are firmware and package. If value is not speicfied, it is assumed to be firmware.

    If you are uploading a package then:

    • it should contain exactly one firmware image with file name format - project_name.bin
    • optional - bootloader image with bootloader.bin name
    • optional - other associated files with any extension

    Paramerer conventions
    • fw_version and model should be provided if not present in the uploaded OTA image binary. It can also be used to override the binary fw_version and model.
    • It returns the S3 URL of the OTA image.
    • If you have uploaded an invalid file, it will be deleted completely. You will have to reupload a valid one on the upload_url again.
    • Specify appropriate value for image_type - firmware/package according to what was uploaded


    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for confirming OTA image upload

    ota_image_id
    required
    string

    The ota_image_id whose upload is to be confirmed

    fw_version
    string
    model
    string
    type
    string
    image_type
    string
    Default: "firmware"

    type of uploaded file. If uploaded file is OTA binary, type is firmware. If uploaded file is zip package of binary, bootloader and other related files, specify type as package.

    Responses

    Request samples

    Content type
    application/json
    {
    • "ota_image_id": "ota_image_id",
    • "fw_version": "1.0",
    • "model": "echo 2",
    • "type": "alexa",
    • "image_type": "package"
    }

    Response samples

    Content type
    application/json
    {
    • "ota_image_id": "string",
    • "image_url": "string",
    • "status": "string"
    }

    This API creates a new OTA job

    This API creates a new OTA job. The user needs to specify the OTA Image ID, Job name, nodes and/or groups.

    Currently, the OTA update can be pushed for upto 100 nodes and/or 10 groups of nodes or all claimed nodes (Group:FFFF-FFFF) in a single request.
    For pushing the OTA Update to a group of nodes, the groups parameter must be filled with a list of group IDs.
    For pushing the OTA update to all the claimed nodes, user needs to specify the group_id as FFFF-FFFF

    The description added to OTA Jobs will be shown to end Users in case of User Approval OTA jobs.

    Dynamic OTA Jobs can be created with config based rules, like an OTA job which will be available to all nodes of a particular type, model, fw_version and combinations among these.
    Note: Dynamic OTA Jobs are never marked as completed. This is because new nodes can always become eligible for the Job at a later time.

    OTA Jobs can also be assigned a priority between 1 and 10, 1 being the highest and 10 being the lowest. Nodes will get an OTA job only after it is done with higher priority jobs.
    OTA Jobs can be assigned a timeout, i.e number of seconds after which the job expires.
    NOTE: The OTA image must have unarchived status.
    IMPORTANT: If OTA image is more than 24 MB in size then nodes cannot download that using streams i.e. MQTT based file delivery won't be available.

    User Approval job with Access to firmware
    For a user approval OTA, user_ota_image_acccess can be specified to grant the firmware binary access to users. The Firmware URL will be returned when user queries for available OTA using /user/nodes/ota_update API.

    Giving securely signed images -

    While creating ota job you can specify to securely sign the ota image before delivering it to node/device.
    There are two ways with which this can be achieved.

    • Specify the key_names - Specify the key name(s) in the request body with which the input ota image will be signed and the signed image will be given to node/device. Note that - Digest of the node should match the digest of the key that you are specifying otherwise node will reject the OTA.
    • Allow RainMaker to select the right key - RainMaker will choose the appropriate key depending on the digest of the nodes in the ota job and sign the image with key before delivering it to node.


    Either auto select signing key or explicit key name in the request can be specified.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    force_push
    string
    Default: "false"

    Force push OTA image

    user_approval
    string
    Default: "false"

    If true, OTA can be pushed to node by end users

    notify
    string
    Default: "false"

    Indicates if end user should be notified about OTA job

    Request Body schema: application/json
    required

    Request body for creating a new OTA Job

    One of
    ota_job_name
    required
    string
    description
    string
    groups
    string
    nodes
    string
    priority
    integer
    timeout
    integer
    node_type
    string
    node_model
    string
    node_fw_version
    string
    ota_image_id
    required
    string
    metadata
    object
    object (SecureBoot)
    user_ota_image_acccess
    boolean

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "ota_job_name": "OTA Job for Alexa devices, FW version 1.0 ",
    • "description": "Sample Description from Admin.",
    • "groups": [
      ],
    • "nodes": [
      ],
    • "priority": 5,
    • "timeout": 1296000,
    • "node_type": "Light",
    • "node_model": "ESPLight",
    • "node_fw_version": "1.0",
    • "ota_image_id": "Image Id which needs to be pushed",
    • "metadata": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "ota_job_id": "string",
    • "status": "string"
    }

    Get the details about OTA jobs for the user

    This API provides the details about the OTA job created by the user.

    1. If the user specifies ota_job_id or ota_job_name, then the details about the specific job are returned. In case of ota_job_name all jobs which contain the pattern are returned.
    2. If ota_image_id is provided then the latest ota job that is not archived by the user with that image id will be returned and if archived is set as true then latest ota job that is archived by the user with that image id will be returned
    3. If archived is provided as true, then the all ota job that are archived by the user will be returned
    4. If all is provided as true, then all the OTA jobs created by the user are returned
    5. else the details about all the OTA jobs that have been created by the user and are not archived will be returned.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    ota_job_id
    string

    OTA Job Id

    ota_job_name
    string

    OTA Job name - Pattern

    ota_image_id
    string

    OTA Image Id

    num_records
    string

    Used for pagination, number of records to be fetched

    start_id
    string

    Used for pagination, Start Id of the record to be fetched

    archived
    boolean
    Default: false

    Flag to get archived ota jobs. [Valid values are true/false]

    all
    boolean
    Default: false

    Flag to get all the ota jobs irrespective whether a job is archived or not. [Valid values are true/false]

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "ota_jobs": [
      ],
    • "total": 0,
    • "next_id": "id of the next record"
    }

    Cancel/Archive an OTA job

    This API cancels/archives OTA job. The user needs to specify the OTA Job Id and archive flag in request body.
    NOTE: An OTA Job can be archived only when it is in finished or cancelled state.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for cancelling/archiving OTA Job

    ota_job_id
    required
    string
    archive
    string

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "ota_job_id": "ota_job_id"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "ota_job_id": "string",
    • "ota_job_name": "string",
    • "ota_image_id": "string",
    • "completed_count": 0,
    • "total_count": 1,
    • "total_node_count": "1,",
    • "triggered_count": "0,",
    • "started_count": "0,",
    • "in_progress_count": "0,",
    • "success_count": "1,",
    • "failed_count": "0,",
    • "other_count": "0,",
    • "triggered_timestamp": "string",
    • "cancelled_timestamp": "string",
    • "groups": [
      ],
    • "status": "cancelled",
    • "stream_id": "string"
    }

    This API provides status of the the OTA job

    This API provides the status of the OTA job. It provides the details about the OTA job and the latest OTA status for the nodes.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    ota_job_id
    required
    string

    OTA Job Id

    node_id
    string

    node Id

    summary
    boolean

    OTA Job summary

    num_records
    string

    Used for pagination, number of records to be fetched

    start_id
    string

    Used for pagination, Start Id of the record to be fetched

    Responses

    Response samples

    Content type
    application/json
    {
    • "node_ota_status": [
      ],
    • "total": 5,
    • "node_groups": [
      ],
    • "next_id": "next_id"
    }

    This API provides summary of the the OTA job

    This API provides the summary of the OTA job. It provides the count of nodes with various OTA status - triggered, in_progress, success, failed and the total count.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    ota_job_id
    required
    string
    Default: "v1"

    OTA Job Id

    Responses

    Response samples

    Content type
    application/json
    {
    • "triggered": 0,
    • "started": 0,
    • "in_progress": 0,
    • "rejected": 0,
    • "delayed": 0,
    • "success": 0,
    • "failed": 0,
    • "total": 0
    }

    API for the end user to upload a new firmware image

    Using this API end user can upload a new firmware image. Using image url received in the response, the user can push the OTA for the device

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for uploading new firmware image. type is optional parameter.

    type
    string
    image_name
    string
    base64_fwimage
    string

    Responses

    Request samples

    Content type
    application/json
    {
    • "type": "Image type",
    • "image_name": "Image name",
    • "base64_fwimage": "base64_fwimage"
    }

    Response samples

    Content type
    application/json
    {
    • "image_url": "string",
    • "status": "string"
    }

    Get latest OTA update for the node associated with the user

    Using this API the end user can check if there is any OTA update, for the node which is associated with his account.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    node_id
    required
    string

    node Id

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "status": "success",
    • "ota_available": true,
    • "description": "Sample Description from Admin.",
    • "fw_version": "1.0",
    • "ota_job_id": "ota_job_id",
    • "file_size": 0
    }

    Push OTA update to the node

    Using this API the end user can push OTA update to the node which is associated with his account

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json

    Request body for uploading new firmware image. ota_job_id and node_id are required parameters.

    ota_job_id
    string
    node_id
    string

    Responses

    Request samples

    Content type
    application/json
    {
    • "ota_job_id": "OTA job Id",
    • "node_id": "node Id"
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Get latest status of OTA update for the node associated with the user

    Using this API the end user can check the latest status of the OTA Job, for node which is associated with his account

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    node_id
    required
    string

    node Id

    ota_job_id
    required
    string

    OTA Job Id

    Responses

    Response samples

    Content type
    application/json
    {
    • "node_id": "node_id",
    • "status": "status",
    • "additional_info": "additional_info",
    • "timestamp": 1584698464101
    }

    Get Pre-signed url to upload the firmware package

    This API is used to fetch presigned url to upload the firmware package. The user needs to specify the file_name including the file extension. If the file_name is specified the pre-signed URL is returned.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    file_name
    required
    string

    Name of the file with file extension

    Responses

    Response samples

    Content type
    application/json
    {
    • "url": "url",
    • "status": "success"
    }

    This API is used for uploading a new package containing the Firmware image

    This API uploads the new package containing the Firmware image to Rainmaker Cloud.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for uploading new firmware package

    image_name
    string
    type
    string
    file_path
    string

    Responses

    Request samples

    Content type
    application/json
    {
    • "image_name": "Alexa echo 2",
    • "type": "alexa",
    • "file_path": "file name that has been uploaded to s3"
    }

    Response samples

    Content type
    application/json
    {
    • "ota_image_id": "string",
    • "image_url": "string",
    • "status": "string"
    }

    File upload

    APIs to upload QA report Files associated to OTA image. (Beta- These APIs are in development stage and may have breaking changes)

    Get Upload URL to upload the file

    This API is used to fetch upload_url (Validity: 1 hour) to upload the files to RainMaker. This API can also be used to upload QA report, bootloader or other files related to an OTA image.

    The user needs to specify the file_name. This file_name is independent of the file name on the host machine. The file_name must be between 1 and 100 characters.

    To verify the integrity of the file uploaded to s3, the user can provide an optional md5 checksum only as per the instructions in the params md5_checksum below.

    Note:

    • The client will have to send a PUT HTTP request to the upload_url with headers -
      'Content-type': 'application/octet-stream'
    • If md5 checksum was added during GET call then the same has to added as an header in the PUT api for upload with headers -
      'Content-MD5': 'correct/valid_md5checksum_of_uploaded_file/image'
    • The value of the Content-MD5 header has to be in the base64 format only. No replacement of symbols like '+' with %2b in the PUT call. Add the md5 checksum in base64 as it is.
    • If upload_url is expired you will get a 403 Forbidden response. You may fetch a new upload_url.
    • Max file size allowed is 100MB

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    file_name
    required
    string

    Name of file to be uploaded.

    entity_id
    required
    string

    Entity Id of file to be uploaded.(e.g. ota_image_id)

    entity_type
    required
    string

    Entity type of file to be uploaded.(e.g. ota_image, cert)

    md5_checksum
    string

    It should be a valid/correct MD5 checksum of the file. It should be in base64 format only. If there are any '+' symbols in the checksum, then they should be replaced by '%2b' while adding as the param value in the GET request.

    Responses

    Response samples

    Content type
    application/json
    {
    • "file_id": "file_id",
    • "file_url": "file_upload_url",
    • "status": "success"
    }

    Confirm file upload

    After the admin uploads the files to S3 bucket, this API needs to be called. It is expected that the admin will upload the file separately using a suitable tool with the help of the upload URL returned by the GET: /admin/file/upload_request.
    It returns the file id and the S3 URL of the file. The URL can be used to download the file.

    Ex. To upload bootloader for a particular firmware image, specify file_type as bootloader.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for confirming file upload. File ID is the ID of the file uploaded. You can provide file_type=qa_report to indicate that file is OTA image QA report. To upload a bootloader for OTA image, provide file_type=bootloader. You can provide additional metadata and description for file.

    file_id
    string

    Unique file ID received in file/upload_request API.

    description
    string

    Add additional comments as file's description

    metadata
    object

    additional details you would like to add for the file

    file_type
    string

    Custom file type, For E.g Specify file_type=qa_report or bootloader to indicate bootloader

    public
    boolean

    Flag for public file upload

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "file_id": "4R2sF4y4g/Y4ytXQzVdumfoTAnUVYRuB",
    • "description": "bootloader",
    • "metatdata": {
      },
    • "file_type": "bootloader"
    }

    Response samples

    Content type
    application/json
    {
    • "file_url": "file_download_url",
    • "file_id": "file_id",
    • "status": "success"
    }

    Get Upload URL to upload the file

    This API is used to fetch upload_url (Validity: 1 hour) to upload the files to RainMaker. This API can also be used to upload QA report, bootloader or other files related to an OTA image.

    The user needs to specify the file_name. This file_name is independent of the file name on the host machine.

    Note:

    • The client will have to send a PUT HTTP request to the upload_url with headers -
      'Content-type': 'application/octet-stream'
    • If upload_url is expired you will get a 403 Forbidden response. You may fetch a new upload_url.
    • Max file size allowed is 10MB
    • Max number of files allowed - 10

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    file_name
    required
    string

    Name of file to be uploaded.

    entity_type
    required
    string

    Entity type of file to be uploaded.

    entity_id
    string

    Entity Id of file to be uploaded.

    Responses

    Response samples

    Content type
    application/json
    {
    • "file_id": "file_id",
    • "file_url": "file_upload_url",
    • "status": "success"
    }

    Confirm file upload

    After the user uploads the files to S3 bucket, this API needs to be called. It is expected that the user will upload the file separately using a suitable tool with the help of the upload URL returned by the GET: /user/file/upload_request.
    It returns the file id and the S3 URL of the file. The URL can be used to download the file.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for confirming file upload. File ID is the ID of the file uploaded. You can provide file_type=image to indicate that file is image. To upload a logs, provide file_type=log. You can provide additional metadata and description for file.

    file_id
    string

    Unique file ID received in file/upload_request API.

    description
    string

    Add additional comments as file's description

    metadata
    object

    additional details you would like to add for the file

    file_type
    string

    Custom file type, For E.g Specify file_type=qa_report or bootloader to indicate bootloader

    public
    boolean

    Flag for public file upload

    Responses

    Request samples

    Content type
    application/json
    {
    • "file_id": "image/Y4ytXQzVdumfoTAnUVYRuB",
    • "description": "Profile pic",
    • "metatdata": {
      },
    • "file_type": "image",
    • "public": false
    }

    Response samples

    Content type
    application/json
    {
    • "file_url": "file_download_url",
    • "file_id": "file_id",
    • "status": "success"
    }

    Get uploaded files

    Returns files uploaded by admin. Specify file_id to get download URL.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string

    API Version (Current supported API Version is 'v1')

    query Parameters
    file_id
    string
    Default: "v1"

    file_id

    file_name
    string

    file_name

    entity_id
    string

    Entity Id, For E.g Specify OTA image ID to fetch associated files

    entity_type
    string

    Entity type, For E.g ota_image

    file_type
    string

    Custom file type, For E.g Specify file_type=qa_report to get QA report files

    num_records
    string
    Default: 25

    This is used for pagination.

    start_id
    string

    This is used for pagination.

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "file_details": [
      ],
    • "total": 0
    }

    Get uploaded files

    Fetches the files uploaded by user. Specify file_id to get download URL.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string

    API Version (Current supported API Version is 'v1')

    query Parameters
    file_id
    string
    Default: "v1"

    file_id

    file_name
    string
    Value: "node"

    file_name

    entity_id
    string

    Entity Id

    entity_type
    string

    Entity type, For E.g image

    file_type
    string

    Custom file type, For E.g Specify file_type=image to get image files

    num_records
    string
    Default: 25

    This is used for pagination.

    start_id
    string

    This is used for pagination.

    Responses

    Response samples

    Content type
    application/json
    {
    • "file_details": [
      ],
    • "total": 0
    }

    IOT Endpoint

    API to fetch IOT Endpoint

    Fetch the IOT endpoint

    This API will Get the IOT endpoint

    Responses

    Response samples

    Content type
    application/json
    {
    • "mqtt_host": "mqtt_host_endpoint"
    }

    Device grouping

    APIs for operations on device groups

    Create admin device group

    This API will create admin device group

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for creating new device group.

    Mandatory Parameters:

    • group_name
    White Spaces are allowed only in between the characters of group_name. Leading and trailing white spaces are not allowed.

    Optional Parameters:
    1. nodes -> the list of nodes to be added to the group.
    2. parent_group_id
    3. description
    4. type
    5. node_fw_version
    6. node_model
    7. node_type
    8. group_metadata
    9. custom_data -> This is a custom group metadata which follows thingshadow JSON rules:

      1. custom_data: {} There will be no change in the metadata also no validation error in the input 3. custom_data -> object of key and value where key will be string and value can be any data type(array, object, string, number , boolean) Metadata will get stored in the above format , new keys will get appended and the existing keys value will get updated accordingly

      10. 4. custom_data: {“key”:null} Metadata JSON keys can be deleted by above syntax 5. If value is array, it will get overwrite and not update


    If the nodes list is not specified, then node group is created, without any nodes in it.
    Note: node_fw_version, node_model, node_type cannot be specified with parent_group_id and nodes.

    One of
    group_name
    required
    string [ 1 .. 256 ]
    parent_group_id
    string
    type
    string
    mutually_exclusive
    boolean
    nodes
    Array of strings
    description
    string
    group_metadata
    object
    custom_data
    object

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "group_name": "group_name",
    • "parent_group_id": "group_id",
    • "type": "metadata",
    • "nodes": [
      ],
    • "description": "description",
    • "group_metadata": {
      },
    • "custom_data": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "group_id": "group_id",
    • "status": "success"
    }

    Update admin device group

    This API will update admin device group

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    group_id
    required
    string

    group Id

    Request Body schema: application/json
    required

    Request body for updating the existing node group.

    1. Using this API, the user can either add or remove the nodes to the group or change the parameters of the group like group name and type.
    2. The value of operation can be add or remove.
    3. While adding or removing nodes, nodes array is required to be specified in the request body.
    4. For updating group name, group_metadata, description,custom_data and type , the new values for these parameters need to be specified.
    5. regroup - this parameter is applicable to only group_query based groups. If a group is created based on a group_query and some nodes' type, model or firmware version is changed, then the regroup option removes nodes which no longer satisfy the group_query and adds newly added/updated nodes which match the group_query.

    group_name
    string
    operation
    string
    type
    string
    nodes
    Array of strings
    description
    string
    regroup
    boolean
    group_metadata
    object
    custom_data
    object

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "group_name": "group_name",
    • "type": "metadata",
    • "operation": "operation",
    • "nodes": [
      ],
    • "description": "description",
    • "group_metadata": {
      },
    • "custom_data": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Get admin device group

    This API will get the details about the admin device group.

    1. By Default all the groups with their sub-groups will be returned
    2. start_id and num_records are used for pagination of groups.
    3. When group_id or group_name is passed then details of that group will be returned, with nodes and subgroups.
      • To get node details set node_details flag to true.
      • start_id and num_records are used for pagination of nodes and node_details.
      • when node details is requested then nodes array will be removed from the output.
    4. If a group is created based on a group_query with some node type, model and firmware version and node_model, node_type and/or node_fw_version are provided, then all the groups that have the exact same group_query filters are returned.
      Note - If for any such group, some nodes' type, model or firmware version is changed, then the regroup option provided in the PUT API should be used.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    group_id
    string

    group Id

    group_name
    string

    group Name

    node_details
    boolean
    Default: false

    optional flag (true/false), to indicate if the node_details is required in the response

    node_type
    string

    node_type in group_query based group searching

    node_model
    string

    node_model in group_query based group searching

    node_fw_version
    string

    node_fw_version in group_query based group searching

    start_id
    string

    This is used for the pagination

    num_records
    string
    Default: 25

    This is used for the pagination

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "groups": [
      ],
    • "total": "<groups_count>",
    • "next_id": "<next group id>"
    }

    Delete admin device group

    This API will delete admin device group

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    group_id
    required
    string

    group id

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Create the user device group or matter fabric

    This API is used for creating new node group as well as new matter fabric.The maximum level for the Node Group hierarchy can be upto three.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required
    • Request body for creating new device group.

      • Mandatory Parameters:
      • group_name
      White Spaces are allowed only in between the characters of group_name. Leading and trailing white spaces are not allowed.

      Optional Parameters:
      1. nodes -> the list of nodes to be added to the group.
      2. parent_group_id
      3. description
      4. group_metadata
      5. type
      6. mutually_exclusive -> When mutually_exclusive flag is true, group will be considered as Mutually exclusive group i.e Nodes which are part of this group can't be part of the other mutually exclusive groups having same group type and same parent(Groups having no parent IDs can also be considered having same parent)

    • custom_data -> This is a custom group metadata which follows thingshadow JSON rules:

      1. custom_data: {} There will be no change in the metadata also no validation error in the input 3. custom_data -> object of key and value where key will be string and value can be any data type(array, object, string, number , boolean) Metadata will get stored in the above format , new keys will get appended and the existing keys value will get updated accordingly

      • 4. custom_data: {“key”:null} Metadata JSON keys can be deleted by above syntax 5. If value is array, it will get overwrite and not update

    • Request body for creating new Matter Fabric.

      • Mandatory Parameters:
      • group_name
      • is_matter

      Optional Parameters:
      1. nodes -> the list of rainmaker nodes to be added to the group.Only subgroups can add matter nodes which are already commissioned in their parent fabric
      2. description
      3. type
      4. group_metadata
      5. custom_data
      6. mutually_exclusive
    If the nodes list is not specified, then node group and matter fabric is created, without any nodes in it.

    One of
    group_name
    required
    string [ 1 .. 256 ]
    parent_group_id
    string
    type
    string
    mutually_exclusive
    boolean
    nodes
    Array of strings
    description
    string
    group_metadata
    object
    custom_data
    object

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "group_name": "group_name",
    • "parent_group_id": "parent_group_id",
    • "type": "group_metadata",
    • "mutually_exclusive": true,
    • "nodes": [
      ],
    • "description": "description",
    • "group_metadata": {
      },
    • "custom_data": {
      }
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "group_id": "group_id",
    • "status": "success"
    }

    Update user device group or matter fabric

    This API will update user device group or matter fabric

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    group_id
    required
    string

    group Id

    matter_controller
    string
    Example: matter_controller=true/false

    Create matter controller.Do not use group_id with this param.

    Request Body schema: application/json
    required

    Device group

    1. Using this API, the user can either add or remove the nodes to the group or change the parameters of the group like group name and type.
    2. The value of operation can be add or remove.
    3. While adding or removing nodes, nodes array is required to be specified in the request body.
    4. For updating group name, description ,group_metadata, custom_data and type , the new values for these parameters need to be specified.
    5. mutually_exclusive -> When mutually_exclusive flag is true, group will be considered as Mutually exclusive group i.e Nodes which are part of this group can't be part of the other mutually exclusive groups having same group type and same parent(Groups having no parent IDs can also be considered having same parent)

    6. custom_data -> This is a custom group metadata which follows thingshadow JSON rules
      1. 1.custom_data -> null The metadata will get deleted entirely
      2. 2. custom_data -> {} There will be no change in the metadata also no validation error in the input
      3. 3. custom_data -> object of key and value where key will be string and value can be any data type(array, object, string, number , boolean) Metadata will get stored in the above format , new keys will get appended and the existing keys value will get updated accordingly
      4. 4. custom_data -> {“key”:null} Metadata JSON keys can be deleted by above syntax
      5. 5. If value is array, it will get overwrite and not update


    Matter fabric
    1. You can update the fabric name,group_metadata,custom_data, type or description or can add rainmaker nodes through add operation.Only subgroups can add matter nodes which are already commissioned in their parent fabric
    2. You can convert an existing node group into the matter fabric.
    3. You can provide a Certificate Signing Request to add a matter node to matter fabric.You can optionally add tags and metadata(This metadata follows the thingshadow JSON rule similar to custom_data above) to the nodes.
    4. You can provide a Certificate Signing Request to get Noc for a user for specified matter fabric.
    5. Confirm the node commissioning with appropriate status by providing the request id received in 'Add node to fabric' step.
    6. You can remove any type of nodes(pure_matter/rainmaker_matter/rainmaker) from the fabric.In the case of pure matter nodes, they will get deleted completely.In the case of rainmaker_matter nodes, they will become just rainmaker nodes
    7. User will no longer be associated with the matter nodes if nodes are removed from the fabric
    8. User can specify both challenge and challenge_response in the rainmaker + matter node commissioning confirmation step as of now.challenge will be deprecated soon
    9. Multi controller is supported where in a controller assume the identity of a matter node to make the API calls. Check the Issue NoC for Controller example. Appropriate support is needed in controller firmware.Also check the Create Matter Controller example to create the matter controller to get the MAtter Node ID for getting NOC

    One of
    group_name
    string
    operation
    string
    type
    string
    is_matter
    boolean
    mutually_exclusive
    boolean
    nodes
    Array of strings
    description
    string
    group_metadata
    object
    custom_data
    object
    Array of objects (Csr_Request)
    csr_type
    string
    tags
    Array of strings
    metadata
    object
    request_id
    string
    status
    string
    rainmaker_node_id
    string
    challenge
    string
    challenge_response
    string

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "group_name": "group_name",
    • "operation": "add/remove",
    • "type": "type",
    • "mutually_exclusive": true,
    • "nodes": [
      ],
    • "description": "description",
    • "group_metadata": {
      },
    • "custom_data": {
      }
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "status": "success",
    • "description": "success description"
    }

    Get user device group

    This API will get the details about the user device group and matter fabrics.

    1. By Default all the groups with their details will be returned.Matter fabrics will also be returned with additional fields i.e is_matter and fabric_id
    2. To get list of nodes in a group or for all groups, set node_list flag to true.
    3. To get sub groups in a group or for all groups, set sub_groups flag to true.
    4. start_id and num_records are used for pagination of groups.
    5. When group_id is passes then details of that group will be returned.
    6. When group_name is passes then details of that group will be returned.
      • To get node details set node_details flag to true.
      • When node details is requested, the nodes array will be removed from the output.
    7. The node_details flag is applicable only when group_id or group_name is passed
    8. The matter_node_list flag is applicable only when group_id or group_name is passed, If true, all the matter node IDs along with their rainmaker IDs get displayed in case of matter nodes.This flag can only be applied if group_id or group_name is present. node_details flag has the higher priority over this flag
    9. When is_matter flag is requested, all the matter fabrics will be displayed.is_matter flag can be used with all the above mentioned flags except group_id/group_name.
    10. When fabric_details flag is requested, fabric details will get displayed.This flag can be used with group_id/group_name/is_matter.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    group_id
    string

    group Id

    optional group_name
    string

    group Name

    node_list
    boolean
    Default: false

    optional flag (true/false), to indicate if the node list is required in the response

    sub_groups
    boolean
    Default: false

    optional flag (true/false), to indicate if the sub groups list is required in the response

    node_details
    boolean
    Default: false

    optional flag (true/false), to indicate if the node_details is required in the response

    is_matter
    boolean
    Default: false

    optional flag (true/false), If true, all the matter fabrics will be displayed

    matter_node_list
    boolean
    Default: false

    optional flag (true/false), If true, all the matter node IDs along with their rainmaker IDs get displayed in case of matter nodes.This flag can only be applied if group_id or group_name is present

    fabric_details
    boolean
    Default: false

    optional flag (true/false), to indicate if the fabric_details is required in the response

    start_id
    string

    This is used for the pagination

    num_records
    string
    Default: 25

    This is used for the pagination

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "groups": [
      ]
    }

    Delete user device group or matter fabric

    This API will delete user device group/matter fabric if user is primary.It allows the users to leave from their own groups/matter fabric. It also allows primary users to remove the sharing for other users

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    group_id
    required
    string

    group id

    leave
    boolean
    Default: false

    Primary/secondary users can specify this parameter to leave the group.For primary users, if that's the only primary for the group, this option won't work and user need to delete the group. For secondary users, it will be true by default if nothing is specified.

    remove_sharing
    boolean
    Default: false

    remove_sharing should be used with user_name

    user_name
    string

    user_name of the user for which sharing needs to be removed

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    This API creates the sharing of Groups or matter fabrics between users.

    This API allows Primary users to share the groups/matter fabrics with other users either with primary or secondary user role. User Name of the secondary user and groups are mandatory parameters.Primary flag to make the users as primary is an optional parameter. Metadata is an optional parameter, used to store additional info about node sharing request.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Add User Group Sharing

    groups
    Array of strings
    user_name
    required
    string
    primary
    boolean
    metadata
    object
    transfer
    boolean
    new_role
    string

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "groups": [
      ],
    • "user_name": "username@domain.com",
    • "primary": true,
    • "metadata": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description",
    • "request_id": "request_id"
    }

    This API fetches the sharing details for the groups and matter fabrics the current user is associated with.

    This API is used to fetch the Group/fabric sharing details. Here are the details -

    • When no parameters are passed it returns the sharing details of all the groups that this user is associated with (Primary or Secondary)
    • When group_id is passed, it returns the sharing details of that group. The requesting user can be Primary or Secondary.
    • When sub_groups is set as true(with or without groupId), it returns the sharing details of the sub groups as well. The requesting user can be Primary or Secondary.
    • When parent_groups is set as true(with or without groupId), it returns the sharing details of the parent groups as well. The requesting user can be Primary or Secondary.
    • If the Get group sharing API is called by the secondary user, the list of other secondary users this group is associated with, will not be returned.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    group_id
    string

    group_id of group to get the sharing details

    sub_groups
    boolean
    Default: false

    When set to true returns details of sub-group as well.

    metadata
    boolean
    Default: false

    When set to true returns metadata that was set during sharing.

    parent_groups
    boolean
    Default: false

    group_id of group to get the sharing details

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "group_sharing": [
      ]
    }

    This API is used to get the sharing requests raised between users.

    This API allows the primary and secondary users to get the sharing requests.

    1. To get the requests raised by primary user, with primary_user flag set as true
    2. To get the requests received by secondary user
    3. To get the details of a request by request_id
    To support pagination start_request_id, start_user_name, num_records are added to the API.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    request_id
    string

    request Id

    primary_user
    string

    This is a boolean flag, which is used to denote whether to get the requests raised by Primary user(true) or received by secondary users (false). Default value for this flag is false.

    start_request_id
    string

    used in pagination

    start_user_name
    string

    used in pagination along with start_request_id

    num_records
    string

    used to specify the no of records that must be returned. Default value is 10. The valid values are in the range of 1 to 10. If invalid value is given, default value is used.

    Responses

    Response samples

    Content type
    application/json
    {
    • "sharing_requests": [
      ],
    • "next_request_id": "next_request_id",
    • "next_user_name": "next_user_name"
    }

    This API removes the sharing request of Groups or matter fabrics between the users.

    This API allows the primary users to remove the sharing request of groups with other users.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    request_id
    required
    string

    Request Id

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    This API creates the sharing of Node Groups or Matter fabrics between users.

    This API allows Secondary or Primary user to accept or decline the request for node group/matter fabrics sharing sent by the primary users.Here accept and request_id are mandatory parameters

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Accept or Decline Sharing Request

    confirm_sharing
    boolean
    request_id
    required
    string
    accept
    required
    boolean

    Responses

    Request samples

    Content type
    application/json
    {
    • "accept": true,
    • "request_id": "request_id"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "status": "success",
    • "description": "Success description"
    }

    This API is used to get the fabric Node ACLs

    This API allows the primary users of the matter fabrics to get the node ACLs

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    group_id
    string

    group_id

    type_entity
    string

    type_entity can be NODE_ACL_ADMIN_ or NODE_ACL_OPERATE_ and it should be provided with group_id

    Responses

    Response samples

    Content type
    application/json
    {
    • "fabric_node_acl": [
      ]
    }

    Time Series Data

    APIs to fetch the Time Series data for the nodes.

    This API is used to get the Time Series Data

    This API is used to get the time series data for various measures like temperature, humidity, electric current, etc. reported by nodes. This information can be queried based on parameter name and aggregation interval.
    The data can be retrieved for different aggregation intervals like minute, hour, day, week, month or year clubbed with query parameters num_intervals to specify the number of interval starting from today or start_time and end_time to specify the date and time range.

    1. Minute - Max Interval: 1 day or 1440 minutes
    2. Hour - Max Interval: 1 day or 24 hours
    3. Day - Max Interval: 31 days and end_time must be strictly greater than the start_time.
    4. Week - Max Interval: 12 weeks. week_start parameter is used to specify the start Day of the week. Ex: Monday
    5. Month - Max Interval: 12 months
    6. Year - Max Interval: 5 years
    7. Raw - Max Interval: 31 days

    Aggregates supported by different data types:

    1. float - All
    2. int - All
    3. bool - raw, latest, count
    4. string - raw, latest, count

    Differential is supported for data of type float and int.

    Note:

  • If aggregate is provided then either start_time and end_time or num_interval needs to be provided for each query.
  • If aggregate is not provided then raw data is returned for last 7 days or given start or end time is returned.
  • The Range of data that is retrieved are [StartTime,EndTime) or [ CurrentTime - NumInterval, CurrentTime)
  • When using start_id the inputs passed (apart from start_id and num_records) need to be kept the same for every call.
  • Aggregate: latest is not supported for AggregationInterval: Month and Year
  • When TimeZone is provided the start time and end time are also need to be in provided time zone

    • Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    node_id
    required
    string
    Example: node_id=node_id1

    This parameter is used to specify the node ID for which measures needs to be fetched.

    param_name
    required
    string
    Example: param_name=temperature

    Some examples of the parameter names are -

  • temperature
  • humidity
  • electric_current
    • A single valid measure need to be passed.

    aggregate
    string
    Default: "raw"
    Example: aggregate=raw

    Following aggregate functions are supported - (To be changed)

  • raw - Returns all the actual values reported by device in given time range. This is the default value for the parameter.
  • latest - Returns the last entry reported by the device for the given aggregation interval and time range
  • min - Returns the min value reported by the device for the given aggregation interval and time range
  • max - Returns the max value reported by the device for the given aggregation interval and time range
  • count - Returns the number of values reported by the device for the given aggregation interval and time range
  • avg - Returns the avg values reported by the device for the given aggregation interval and time range
  • sum - Returns the sum of values reported by the device for the given aggregation interval and time range

    • Only one aggregate function can be specified at a time.

    aggregation_interval
    string

    This parameter is used to specify the aggregation interval for the params. They can be -

  • minute
  • hour
  • day
  • week
  • month
  • year

    • It is not applicable when aggregate is passed as raw.

    differential
    boolean
    Default: false

    If differential then to apply aggregates the data is on the incremental values and then apply the aggregates i.e. for T1 the value will be V1 - V0 on which the aggregates will be applied.
    Note: Differential is supported for data of type float and int

    reset_on_negative
    boolean
    Default: false

    Only applicable when differential is true, else ignored. If reset_on_negative is true, then the value will be reset to present value if the difference is negative.

    desc_order
    boolean
    Default: false

    This is set to true if the timeseries data to retrieve should be in descending order

    type
    string
    Default: "float"
    Example: type=float

    This parameter is used to specify the data type of the param. They can be -

  • float
  • int
  • bool
  • string

    • week_start
    string
    Default: "Monday"

    This parameter is used to specify the start day of the week. This field is case insensitive. Only applicable in cases were the time_interval value is week.

    start_time
    number

    This parameter is used to set the start time. The expected Format for start time is epoch time in seconds. Ex: 1628557200

    end_time
    number

    This parameter is used to set the end time. The expected Format for end_date is epoch time in seconds. Ex: 1628557200

    num_intervals
    number

    The user can specify either the start_time and end_time or num_intervals parameter. If the num_intervals is specified, then the API will fetch the data from the current time for the previous 'n' intervals.

    i.e
    If time_interval=day, aggregate=avg, parameter_name=temperature , device_id=1234
    num_intervals=5
    The output would have data for previous 5 days starting from today. Not Applicable for Aggregate=Raw.

    start_id
    string

    This parameter is used for pagination.
    The pagination token can be used for up to 5 Query Invocations, OR for a duration of up to 1 hour whichever comes first.

    num_records
    number <= 200
    Default: 200

    This parameter is used for pagination. Max Value = 200

    timezone
    string
    Default: "UTC"
    Example: timezone=Asia/Shanghai

    This parameter is used to set the timezone(location) from where the query is made, based on IANA Tz Database name. TimeZone can also be provided like EST but location name is preferred. This field is case-insensitive.

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "ts_data": [
      ]
    }

    This API is used by Admins to get Time Series Data

    This API is used to get the time series data for various measures like temperature, humidity, electric current, etc. reported by nodes. This information can be queried based on parameter name and aggregation interval.
    The data can be retrieved for different aggregation intervals like minute, hour, day, week, month or year clubbed with query parameters num_intervals to specify the number of interval starting from today or start_time and end_time to specify the date and time range.

    1. Minute - Max Interval: 1 day or 1440 minutes
    2. Hour - Max Interval: 1 day or 24 hours
    3. Day - Max Interval: 31 days and end_time must be strictly greater than the start_time.
    4. Week - Max Interval: 12 weeks. week_start parameter is used to specify the start Day of the week. Ex: Monday
    5. Month - Max Interval: 12 months
    6. Year - Max Interval: 5 years
    7. Raw - Max Interval: 31 days

    Aggregates supported by different data types:

    1. float - All
    2. int - All
    3. bool - raw, latest, count
    4. string - raw, latest, count

    Differential is supported for data of type float and int.

    Note:

  • If aggregate is provided then either start_time and end_time or num_interval needs to be provided for each query.
  • If aggregate is not provided then raw data is returned for last 7 days or given start or end time is returned.
  • The Range of data that is retrieved are [StartTime,EndTime) or [ CurrentTime - NumInterval, CurrentTime)
  • When using start_id the inputs passed (apart from start_id and num_records) need to be kept the same for every call.
  • Aggregate: latest is not supported for AggregationInterval: Month and Year
  • When TimeZone is provided the start time and end time are also need to be in provided time zone

    • Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    node_id
    required
    string
    Example: node_id=node_id1

    This parameter is used to specify the node ID for which measures needs to be fetched.

    param_name
    required
    string
    Example: param_name=temperature

    Some examples of the parameter names are -

  • temperature
  • humidity
  • electric_current
    • A single valid measure need to be passed.

    aggregate
    string
    Default: "raw"
    Example: aggregate=raw

    Following aggregate functions are supported - (To be changed)

  • raw - Returns all the actual values reported by device in given time range. This is the default value for the parameter.
  • latest - Returns the last entry reported by the device for the given aggregation interval and time range
  • min - Returns the min value reported by the device for the given aggregation interval and time range
  • max - Returns the max value reported by the device for the given aggregation interval and time range
  • count - Returns the number of values reported by the device for the given aggregation interval and time range
  • avg - Returns the avg values reported by the device for the given aggregation interval and time range
  • sum - Returns the sum of values reported by the device for the given aggregation interval and time range

    • Only one aggregate function can be specified at a time.

    aggregation_interval
    string

    This parameter is used to specify the aggregation interval for the params. They can be -

  • minute
  • hour
  • day
  • week
  • month
  • year

    • It is not applicable when aggregate is passed as raw.

    differential
    boolean
    Default: false

    If differential then to apply aggregates the data is on the incremental values and then apply the aggregates i.e. for T1 the value will be V1 - V0 on which the aggregates will be applied.
    Note: Differential is supported for data of type float and int

    reset_on_negative
    boolean
    Default: false

    Only applicable when differential is true, else ignored. If reset_on_negative is true, then the value will be reset to present value if the difference is negative.

    desc_order
    boolean
    Default: false

    This is set to true if the timeseries data to retrieve should be in descending order

    type
    string
    Default: "float"
    Example: type=float

    This parameter is used to specify the data type of the param. They can be -

  • float
  • int
  • bool
  • string

    • week_start
    string
    Default: "Monday"

    This parameter is used to specify the start day of the week. This field is case insensitive. Only applicable in cases were the time_interval value is week.

    start_time
    number

    This parameter is used to set the start time. The expected Format for start time is epoch time in seconds. Ex: 1628557200

    end_time
    number

    This parameter is used to set the end time. The expected Format for end_date is epoch time in seconds. Ex: 1628557200

    num_intervals
    number

    The user can specify either the start_time and end_time or num_intervals parameter. If the num_intervals is specified, then the API will fetch the data from the current time for the previous 'n' intervals.

    i.e
    If time_interval=day, aggregate=avg, parameter_name=temperature , device_id=1234
    num_intervals=5
    The output would have data for previous 5 days starting from today. Not Applicable for Aggregate=Raw.

    start_id
    string

    This parameter is used for pagination.
    The pagination token can be used for up to 5 Query Invocations, OR for a duration of up to 1 hour whichever comes first.

    num_records
    number <= 200
    Default: 200

    This parameter is used for pagination. Max Value = 200

    timezone
    string
    Default: "UTC"
    Example: timezone=Asia/Shanghai

    This parameter is used to set the timezone(location) from where the query is made, based on IANA Tz Database name. TimeZone can also be provided like EST but location name is preferred. This field is case-insensitive.

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "ts_data": [
      ]
    }

    Simple Time Series Data

    APIs to fetch the Simple Time Series data for the nodes.

    This API is used to get the Simple Time Series Data

    This API is used to get the simple time series data for various measures like temperature, humidity, electric current, etc. reported by nodes. This information can be queried based on parameter name, data type and time interval(start_time and end_time).

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    node_id
    required
    string
    Example: node_id=node_id1

    This parameter is used to specify the node ID for which measures needs to be fetched.

    param_name
    required
    string
    Example: param_name=temperature

    Some examples of the parameter names are -

  • temperature
  • humidity
  • electric_current
    • A single valid measure need to be passed.

    start_time
    required
    number
    Example: start_time=1628557200

    This parameter is used to set the start time. The expected Format for start time is epoch time in seconds. Ex: 1628557200

    end_time
    required
    number
    Example: end_time=1628557200

    This parameter is used to set the end time. The expected Format for end_date is epoch time in seconds. Ex: 1628557200

    data_type
    required
    string
    Example: data_type=int

    This parameter is used to specify the data type of the param. They can be -

  • float
  • int
  • bool
  • string

    • start_id
    string

    This parameter is used for pagination.

    num_records
    number <= 200
    Default: 200

    This parameter is used to specify number of records. Max Value = 200

    Responses

    Response samples

    Content type
    application/json
    {
    • "ts_data": [
      ]
    }

    This API is used by Admins to get Simple Time Series Data

    This API is used to get the simple time series data for various measures like temperature, humidity, electric current, etc. reported by nodes. This information can be queried based on parameter name, data type and time interval(start_time and end_time).

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    node_id
    required
    string
    Example: node_id=node_id1

    This parameter is used to specify the node ID for which measures needs to be fetched.

    param_name
    required
    string
    Example: param_name=temperature

    Some examples of the parameter names are -

  • temperature
  • humidity
  • electric_current
    • A single valid measure need to be passed.

    start_time
    required
    number
    Example: start_time=1628557200

    This parameter is used to set the start time. The expected Format for start time is epoch time in seconds. Ex: 1628557200

    end_time
    required
    number
    Example: end_time=1628557200

    This parameter is used to set the end time. The expected Format for end_date is epoch time in seconds. Ex: 1628557200

    data_type
    required
    string
    Example: data_type=int

    This parameter is used to specify the data type of the param. They can be -

  • float
  • int
  • bool
  • string

    • start_id
    string

    This parameter is used for pagination.

    num_records
    number <= 200
    Default: 200

    This parameter is used to specify number of records. Max Value = 200

    Responses

    Response samples

    Content type
    application/json
    {
    • "ts_data": [
      ]
    }

    Custom User Data

    User specific data management

    Get the Custom user data

    Fetches the custom user data of the logged-in user.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "membership_info": {
      },
    • "esp.location": {
      },
    • "profile": {
      },
    • "preferences": {
      }
    }

    Store the custom User data

    To store or update the custom user data of the logged-in user. Operations on Data:

    • The data can be deleted by putting data: null.
    • If the key is already present, then the value will be replaced. Arrays will also be replaced entirely.
    • If the key is not present, then the value will be added.
    • If the value is null, then the key-value will be deleted.
    Note: The JSON size should not exceed 399 KB.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    additional property
    object (MapItem)
    value
    object
    Array of objects

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "membership_info": {
      },
    • "esp.location": {
      },
    • "profile": {
      },
    • "preferences": {
      },
    • "demographics": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "membership_info": {
      },
    • "esp.location": {
      },
    • "profile": {
      },
    • "preferences": {
      }
    }

    Webhook Integration

    API to manage the configuration for Webhook integration.

    Get user node webhook integration information.

    This API will get the user node webhook integrations (Beta- These APIs are in development stage and may have breaking changes)

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    webhook_name
    string

    Webhook to be retrieved

    Responses

    Response samples

    Content type
    application/json
    {
    • "webhook_user_node_integrations": [
      ]
    }

    This API adds webhook user node integration

    This API adds the webhook for user node integration (Beta- These APIs are in development stage and may have breaking changes)

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json

    request body for adding a webhook for user node integration.

    webhook_name
    required
    string
    enabled
    boolean
    nodes_list
    Array of strings (NodesList)
    Array of objects (WebhookUserNodeIntegrationEvents) <= 100 items
    active_timestamp
    integer

    Responses

    Request samples

    Content type
    application/json
    {
    • "webhook_name": "test_webhook212",
    • "enabled": true,
    • "nodes_list": [
      ],
    • "events": [
      ],
    • "active_timestamp": 1626684122
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    This API updates webhook user node integration.

    This API updates the webhook for user node integration (Beta- These APIs are in development stage and may have breaking changes)

    IMPORTANT NOTES
    - Identifiers (ex. webhook_name, event_name) cannot be updated.
    - Only respective request body parameters according to operation will be updated. Any additional ones will be ignored. For example, if 'operation' is 'update_enabled', then only the 'enabled' parameter from request body would be updated, rest all would be ignored.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    operation
    required
    string

    Operation to be performed (Supported operations:- update_enabled, add_nodes, remove_nodes, add_event, remove_event, update_event, update_active_timestamp)

    Request Body schema: application/json

    request body for updating a webhook for user node integration.

    webhook_name
    required
    string
    enabled
    boolean
    nodes_list
    Array of strings (NodesList)
    Array of objects (WebhookUserNodeIntegrationEvents) <= 100 items
    active_timestamp
    integer

    Responses

    Request samples

    Content type
    application/json
    {
    • "webhook_name": "test_webhook212",
    • "enabled": true,
    • "nodes_list": [
      ],
    • "events": [
      ],
    • "active_timestamp": 1626684122
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    This API deletes webhook user node integration

    This API deletes the webhook for user node integration (Beta- These APIs are in development stage and may have breaking changes)

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    webhook_name
    required
    string

    Webhook to be deleted

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Event Filter

    API to manage event filtering information events related to Integrations, by Admins.

    This API adds event filter for given event and entity (system, user, node).

    This API adds new event filter for specified event type and entity id (user or node id)
    The event filter hierarchy is examined. System level is examined first, followed by user level and node level.

    Event Type :  These are the events generated by Rainmaker. Please refer the following list of possible events:

    Event
    		 Event type
    		 Entity Id for System
    o User Node Added rmaker.event.user_node_addedsystem.rmaker.event.user_node_added
    o User Node Removed rmaker.event.user_node_removedsystem.rmaker.event.user_node_removed
    o Node Shared with User rmaker.event.user_node_sharing_addsystem.rmaker.event.user_node_sharing_add
    o Node Connected rmaker.event.node_connectedsystem.rmaker.event.node_connected
    o Node Disconnected rmaker.event.node_disconnectedsystem.rmaker.event.node_disconnected
    o Node params change rmaker.event.node_params_changedsystem.rmaker.event.node_params_changed
    o Node Automation Trigger rmaker.event.node_automation_triggersystem.rmaker.event.node_automation_trigger
    o Group Shared with User rmaker.event.user_node_group_sharing_addsystem.rmaker.event.user_node_group_sharing_add
    o Group added rmaker.event.user_node_group_addedsystem.rmaker.event.user_node_group_added
    o Group removed rmaker.event.user_node_group_removedsystem.rmaker.event.user_node_group_removed
    o Node alerts rmaker.event.alertsystem.rmaker.event.alert
    o Node config changed rmaker.event.node_config_changedsystem.rmaker.event.node_config_changed
    o User approval OTA available rmaker.event.user_node_otasystem.rmaker.event.user_node_ota
    o Node time series data rmaker.event.node_ts_datasystem.rmaker.event.node_ts_data

    o Not eligible for User and Node as Entity type
    o Enabled by default for User and Node as Entity type

    Entity Type :  can be User or Node or System (Case insensitive).

    Entity Id        : User - userId, Node - nodeId, System - System Entity Id for that event (Refer the above table). 

    Enabled:  This denotes if the given Event is enabled for the given EntityId.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json

    request body for creating new event filter.

    event_type
    required
    string

    RainMaker event type

    entity_id
    required
    string

    Entity Id
    When entity type is USER, user's UserId should match with Entity-Id.
    When entity type is NODE, nodeId should be associated with the user.

    entity_type
    required
    string
    Enum: "User" "Node" "System"

    Entity type

    enabled
    required
    boolean

    Indicates whether to enable or disable filter

    enabled_for_integrations
    required
    Array of strings

    List of added Intergrations

    Responses

    Request samples

    Content type
    application/json
    {
    • "event_type": "rmaker.event.user_node_added",
    • "entity_id": "56d76757-2609-48bc-bbf5-2e4c6f0723e0",
    • "entity_type": "User",
    • "enabled": false,
    • "enabled_for_integrations": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    This API updates event filter for given event and entity (system, user, node)

    This API updates event filter for given event type and entity id (user or node id) The event filter hierarchy is examined. System level is examined first, followed by user level and node level.

    Event Type :  These are the events generated by Rainmaker. Please refer the following list of possible events:

    Event
    		 Event type
    		 Entity Id for System
    o User Node Added rmaker.event.user_node_addedsystem.rmaker.event.user_node_added
    o User Node Removed rmaker.event.user_node_removedsystem.rmaker.event.user_node_removed
    o Node Shared with User rmaker.event.user_node_sharing_addsystem.rmaker.event.user_node_sharing_add
    o Node Connected rmaker.event.node_connectedsystem.rmaker.event.node_connected
    o Node Disconnected rmaker.event.node_disconnectedsystem.rmaker.event.node_disconnected
    o Node params change rmaker.event.node_params_changedsystem.rmaker.event.node_params_changed
    o Node Automation Trigger rmaker.event.node_automation_triggersystem.rmaker.event.node_automation_trigger
    o Group Shared with User rmaker.event.user_node_group_sharing_addsystem.rmaker.event.user_node_group_sharing_add
    o Group added rmaker.event.user_node_group_addedsystem.rmaker.event.user_node_group_added
    o Group removed rmaker.event.user_node_group_removedsystem.rmaker.event.user_node_group_removed
    o Node alerts rmaker.event.alertsystem.rmaker.event.alert
    o Node config changed rmaker.event.node_config_changedsystem.rmaker.event.node_config_changed
    o User approval OTA available rmaker.event.user_node_otasystem.rmaker.event.user_node_ota


    o Not eligible for User and Node as Entity type
    o Enabled by default for User and Node as Entity type

    Entity Type :  can be User or Node or System (Case insensitive).

    Entity Id        : User - userId, Node - nodeId, System - System Entity Id for that event (Refer the above table). 

    Enabled:  This denotes if the given Event is enabled for the given EntityId.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json

    request body for updating event filter.

    event_type
    required
    string

    RainMaker event type

    entity_id
    required
    string

    Entity Id
    When entity type is USER, user's UserId should match with Entity-Id.
    When entity type is NODE, nodeId should be associated with the user.

    entity_type
    required
    string
    Enum: "User" "Node" "System"

    Entity type

    enabled
    required
    boolean

    Indicates whether to enable or disable filter

    enabled_for_integrations
    required
    Array of strings

    List of added Intergrations

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "event_type": "rmaker.event.node_connected",
    • "entity_id": "system.rmaker.event.node_connected",
    • "entity_type": "System",
    • "enabled": "true/false",
    • "enabled_for_integrations": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Get Integration event filter information.

    This API will get the integration event filter information for given event_type and entity(type/id).
    If event_type and entity id(user or node id) are specified, then the event filter information will be returned for that event_type and entity.
    If the entity type(user or node) is specified, then all the event filter information will be returned for the event_type.
    If just entity id(user or node id) is provided, then all the event filter mapped to that entity id will be returned.
    Either of event_type(optionally with entity_type) or entity_id is required

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    event_type
    string
    Example: event_type=rmaker.event.node_connected

    RainMaker event type

    entity_type
    string
    Enum: "User" "Node" "System"

    Entity type

    entity_id
    string
    Example: entity_id=thing

    Entity Id

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "event_entity_mapping_list": [
      ],
    • "total": 2
    }

    This API removes the Integration event filter.

    This API allows admin to remove Event Filter. This api requires request body:
    {
    "event_type": "rmaker.event.user_node_sharing_add",
    "entity_id": "system.rmaker.event.user_node_sharing_add"
    }

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Event Filter for Users

    API to manage event filtering information events related to Integrations, by Users.

    This API adds event filter for given event and entity (user or node).

    This API adds new event filter for specified event type and entity id (user or node id)

    Event Type :  These are the events generated by Rainmaker. Please refer the following list of possible events:

    Event
    		 Event type
    o Node Connected rmaker.event.node_connected
    o Node Disconnected rmaker.event.node_disconnected
    o Node config changed rmaker.event.node_config_changed

    o Enabled by default for User and Node as Entity type

    Entity Type :  can be User or Node (Case insensitive).

    Entity Id        : User - userId, Node - nodeId  

    Enabled:  This denotes if the given Event is enabled for the given EntityId.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json

    request body for creating new event filter.

    event_type
    required
    string

    RainMaker event type

    entity_id
    required
    string

    Entity Id
    When entity type is USER, user's UserId should match with Entity-Id.
    When entity type is NODE, nodeId should be associated with the user.

    entity_type
    required
    string
    Enum: "User" "Node"

    Entity type

    enabled
    required
    boolean

    Indicates whether to enable or disable filter

    enabled_for_integrations
    required
    Array of strings

    List of added Intergrations

    Responses

    Request samples

    Content type
    application/json
    {
    • "event_type": "rmaker.event.node_connected",
    • "entity_id": "56d76757-2609-48bc-bbf5-2e4c6f0723e0",
    • "entity_type": "User",
    • "enabled": false,
    • "enabled_for_integrations": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    This API updates event filter for given event and entity (user or node)

    This API updates event filter for given event type and entity id (user or node id)

    Event Type :  These are the events generated by Rainmaker. Please refer the following list of possible events:

    Event
    		 Event type
    o Node Connected rmaker.event.node_connected
    o Node Disconnected rmaker.event.node_disconnected
    o Node config changed rmaker.event.node_config_changed

    o Enabled by default for User and Node as Entity type

    Entity Type :  can be User or Node (Case insensitive).

    Entity Id        : User - userId, Node - nodeId  

    Enabled:  This denotes if the given Event is enabled for the given EntityId.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json

    request body for updating event filter.

    event_type
    required
    string

    RainMaker event type

    entity_id
    required
    string

    Entity Id
    When entity type is USER, user's UserId should match with Entity-Id.
    When entity type is NODE, nodeId should be associated with the user.

    entity_type
    required
    string
    Enum: "User" "Node"

    Entity type

    enabled
    required
    boolean

    Indicates whether to enable or disable filter

    enabled_for_integrations
    required
    Array of strings

    List of added Intergrations

    Responses

    Request samples

    Content type
    application/json
    {
    • "event_type": "rmaker.event.node_connected",
    • "entity_id": "56d76757-2609-48bc-bbf5-2e4c6f0723e0",
    • "entity_type": "User",
    • "enabled": false,
    • "enabled_for_integrations": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Get Integration event filter information.

    This API will get the integration event filter information for given event_type and entity(type/id).
    If event_type and entity id(user or node id) are specified, then the event filter information will be returned for that event_type and entity.
    If the entity type(user or node) is specified, then all the event filter information will be returned for the event_type.
    If just entity id(user or node id) is provided, then all the event filter mapped to that entity id will be returned.
    Either of event_type(optionally with entity_type) or entity_id is required

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    event_type
    string
    Example: event_type=rmaker.event.node_connected

    RainMaker event type

    entity_type
    string
    Enum: "User" "Node" "System"

    Entity type

    entity_id
    string
    Example: entity_id=thing

    Entity Id

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "event_entity_mapping_list": [
      ],
    • "total": 2
    }

    This API removes the Integration event filter.

    This API allows user to remove Event Filter. This api requires request body:
    {
    "event_type": "rmaker.event.user_node_sharing_add",
    "entity_id": "system.rmaker.event.user_node_sharing_add"
    }

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Mobile Platform Endpoint

    Manage platform endpoint

    Creates the new platform endpoint for the user's Mobile device

    This API will be called from the Mobile App by the end user, to subscribe to Push Notification.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for creating new platform application, Valid values for platform are GCM, APNS or APNS_SANDBOX.

    platform
    string
    Enum: "GCM" "APNS" "APNS_SANDBOX"

    Name of the platform

    mobile_device_token
    string

    Mobile device token

    platform_type
    string
    Enum: "huawei" "glory" "millet" "meizu" "oppo" "vivo" "fcm" "asus"

    Mobile device type (Applicable only for China region)

    Responses

    Request samples

    Content type
    application/json
    {
    • "platform": "GCM",
    • "mobile_device_token": "<device token>",
    • "platform_type": "huawei"
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "platform_endpoint_arn": "platform endpoint arn"
    }

    This API fetches configured platform endpoints

    This API fetches configured platform endpoints

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Responses

    Response samples

    Content type
    application/json
    {
    • "platform_endpoints": [
      ]
    }

    This API removes the configured platform endpoint.

    This API removes the configured platform endpoint. Either mobile_device_token or endpoint must be specified in query params.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    mobile_device_token
    string

    mobile device token

    endpoint
    string

    platform endpoint ARN

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Automation Trigger and Actions

    APIs for operations on automation trigger and actions

    This API adds new automation trigger

    This API adds new automation trigger.

    For Daylight-based Automations provide 'location' and specify the 'event_type' as 'daylight'. The supported events are 'sunrise' and 'sunset'.

    For Weather-based Automations provide 'location' and specify the 'event_type' as 'weather'. The supported events are 'temperature', 'pressure', 'humidity', 'wind_speed' and 'weather_condition'.

    For Location-based Automation Triggers provide positive coordinates for North latitude and East longitude. Conversely, provide negative coordinates for South latitude and West longitude. For eg. 18.5204° N, 73.8567° E transforms to 18.5204,73.8567 and 18.5204° S, 73.8567° W transforms to -18.5204,-73.8567

    List of all parameters and supported units:

    Parameter
    		 Description
    		 Standard
    		 Metric
    		 Imperial
    o temperature Temperature Kelvin Celsius Fahrenheit
    o pressure Atmospheric Pressure hPa hPa hPa
    o humidity Humidity % % %
    o wind_speed Wind Speed meter/sec meter/sec miles/hour
    o weather_condition Weather Condition check note check note check note

    Note: The supported weather conditions are 'Thunderstorm', 'Drizzle', 'Rain', 'Snow', 'Clear', 'Clouds', 'Mist', 'Smoke', 'Haze', 'Dust', 'Fog', 'Sand', 'Ash', 'Squall', 'Tornado'

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for creating new automation trigger.

    name
    string [ 1 .. 256 ] characters

    Automation Name
    It is Unique per node for a user
    It is multilingual compatible

    node_id
    string

    Indicate the nodeId that the automation is being created for.
    Node Id is not required for Location Triggers

    event_type
    string

    event type
    For custom specify any value for E.g 'node_params'
    For Daylight-based Automations specify the 'event_type' as 'daylight'
    For Weather-based Automations specify the 'event_type' as 'weather'

    metadata
    object

    This is a custom metadata field of any type(string, array, json, etc) which gets overridden with update.

    object
    Array of objects [ 1 .. 5 ] items

    Specify event for which you want to create automation

    event_operator
    string
    Enum: "and" "or"

    Indicate if all of the events must match or just one of them must match.

    Array of objects [ 1 .. 10 ] items

    Specify action to be performed if event matches

    retrigger
    boolean
    Default: false

    Specify if action is to be triggered multiple times for the same event

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "name": "automation_name",
    • "node_id": "node_id",
    • "event_type": "node_params",
    • "metadata": "metadata",
    • "events": [
      ],
    • "event_operator": "and",
    • "actions": [
      ],
    • "retrigger": false
    }

    Response samples

    Content type
    application/json
    {
    • "automation_id": "<automation_id>",
    • "status": "success"
    }

    This API updates existing automation trigger.

    This API updates existing automation trigger

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    automation_id
    required
    string

    automation_id

    Request Body schema: application/json
    required

    Request body for updating existing automation trigger.

    name
    string [ 1 .. 256 ] characters

    Automation Name
    It is Unique per node for a user
    It is multilingual compatible

    enabled
    boolean

    Indicate if you want to enable or disable the automation trigger.

    node_id
    string

    Indicate the nodeId that the automation is being created for.
    Node Id is not required for Location Triggers

    metadata
    object

    This is a custom metadata field of any type(string, array, json, etc) which gets overridden with update.

    object
    Array of objects [ 1 .. 5 ] items

    Specify event for which you want to create automation

    Array of objects [ 1 .. 10 ] items

    Specify action to be performed if event matches

    retrigger
    boolean

    Specify if action is to be triggered multiple times for the same event

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "name": "<automation_name>",
    • "enabled": false,
    • "events": [
      ],
    • "event_operator": "and",
    • "actions": [
      ],
    • "retrigger": false
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Get Automation trigger.

    This API will fetch automation trigger

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    automation_id
    string

    Specify Automation Id

    node_id
    string

    Specify Node Id

    start_id
    string

    use next_id from the response as start_id to fetch the next set of records

    num_records
    string

    number of records to fetch

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "automation_name": "automation_name",
    • "automation_id": "automation_id",
    • "enabled": "true",
    • "node_id": "node_id",
    • "event_type": "event_type",
    • "metadata": "metadata",
    • "events": [
      ],
    • "event_operator": "event_operator",
    • "actions": [
      ],
    • "retrigger": "false"
    }

    This API removes the automation trigger.

    This API allows user to remove created automation trigger

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    automation_id
    required
    string

    Specify Automation Id

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Roles and Policy Manager

    APIs to manage user roles and policies.

    This API adds policy

    This API adds new policy

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for creating new policy.

    policy_name
    required
    string [ 2 .. 256 ] characters

    Policy Name is unique
    Policy name cannot begin with RM_DEFAULT_

    object

    Maximum size is 2KB

    Responses

    Request samples

    Content type
    application/json
    {
    • "policy_name": "<policy_name>",
    • "policy_json": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    This API updates existing policy.

    This API updates existing policy.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    policy_name
    required
    string

    Specify policy name
    Default Policies that start with RM_DEFAULT_ cannot be updated

    Request Body schema: application/json
    required

    Request body for updating existing policy.

    object

    Maximum size is 2KB

    version
    string

    Specify policy version

    Array of objects

    Define the conditions or criteria for which the policy statements apply.
    Currently filters are applicable only for resource - /admin/nodes. For other resources, the filters are ignored.

    required
    Array of objects

    Defines list of allowed/denied actions on resources

    Responses

    Request samples

    Content type
    application/json
    {
    • "policy_json": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    This api fetches policies.

    This API will fetch policies

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    policy_name
    string

    Specify policy name

    Responses

    Response samples

    Content type
    application/json
    {
    • "policies": [
      ]
    }

    This API removes the policy.

    This API allow to remove policy

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    policy_name
    required
    string

    Policy_name
    Default Policies that start with RM_DEFAULT_ cannot be deleted
    Policy cannot be deleted if it is linked to a role

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    This API adds new roles

    This API adds new role.
    Specify policies in the request body to attach policies to the role.

    The role level determines the user's authorization to assign a specific role to another user. The user must possess a role with a role level that is greater than the role level of the role being assigned. The highest role level is 0, which means a user with a role level of 0 can assign any role to another user. There is no maximum limit on the role level value.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for creating new role.

    role_name
    required
    string [ 2 .. 256 ] characters

    Role Name is unique
    Role name cannot begin with RM_DEFAULT_

    policies
    required
    Array of strings [ 1 .. 10 ] items

    Valid policies

    role_level
    number >= 1

    The role level of the current role is used to determine whether a user has the ability to assign a certain role to another user.

    Responses

    Request samples

    Content type
    application/json
    {
    • "role_name": "<role_name>",
    • "policies": [
      ],
    • "role_level": 1
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    This API updates existing role.

    This API updates existing role.This API can be used to add/remove the policies from the role or to change the role level value

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    role_name
    required
    string

    Specify role_name
    Default roles that start with RM_DEFAULT_ cannot be updated

    operation
    required
    string

    operation can be add or remove

    Request Body schema: application/json
    required

    Request body for updating existing role.

    policies
    Array of strings [ 1 .. 10 ] items

    Valid policies
    When a role contains just one policy and is assigned to a user, it is not possible to remove the policy

    role_level
    number >= 1

    The role level of the current role is used to determine whether a user has the ability to assign a certain role to another user.

    Responses

    Request samples

    Content type
    application/json
    {
    • "policies": [
      ],
    • "role_level": 2
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    This api fetches roles.

    This API will fetch roles

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    role_name
    string

    Specify role name

    Responses

    Response samples

    Content type
    application/json
    {
    • "roles": [
      ]
    }

    This API removes the roles.

    This API allow to remove role

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    role_name
    required
    string

    Role Name
    Default roles that start with RM_DEFAULT_ cannot be deleted
    Role cannot be deleted if it is linked to a user

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    User Role Mapping

    APIs to assign or remove roles to or from user.

    This API assigns or removes role from or to user.

    This API assigns or removes role from or to user.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    user_name
    required
    string

    user_name

    user_id
    string

    user_id

    operation
    required
    string
    Enum: "add" "remove"

    Specify operation

    Request Body schema: application/json
    required

    Request body for updating user role mapping.

    roles
    Array of strings non-empty

    List of valid roles to be added or removed to/from a user
    Superadmin is able to add/remove any role to/from any user,
    Removing or adding roles from another user is only possible if the user's role level is lower than the role that is being attached.
    Note- Lower role level value have higher precedence, For E.g value 2 has higher precendence than value 3

    Responses

    Request samples

    Content type
    application/json
    {
    • "roles": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    This api fetches roles for a user.

    This API will fetches roles for a user.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    user_name
    string

    user_name

    user_id
    string

    user_id

    role_name
    string

    role_name

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "roles": [
      ]
    }

    Command Response Communication

    Get the Command Response Requests

    Get the Command Response Requests for a given filter criteria.
    You can query the command response request by either of the following ways,

    • request_id: If just request id is given then a matching single record will be returned
    • request_id and node_id: If request id along with node id is is provided then a matching single record will be returned
    • node_id with start_time and end_time: If node id along with start time and end time is provided then all requests between that time interval will be returned
    • node_id with optional cmd_id: If node id is provided then response will have all the command response requests(paginated) for input node id. Optinally you can send the cmd_id parameter to filter out the requests.
    • node_id with optional status: If node id is provided then response will have all the command response requests(paginated) for input node id. Optinally you can send the status parameter to filter out the requests.
    • status: If you just provide the status parameter then all the command response requests added by current user matching the input status will be returned

    Valid values for status parameter are requested, in_progress, success, timed_out, failure

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    request_id
    string

    ID of the command response request.

    node_id
    string

    ID of the node

    status
    string

    status of command

    start_time
    number

    Start time of the requests.

    end_time
    number

    End time of the requests.

    cmd_id
    number

    command id of command

    start_id
    string

    Used for pagination.

    num_records
    number
    Default: 10

    Used for pagination, number of records to be fetched.

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "requests": [
      ],
    • "total": 10,
    • "next_id": "some id"
    }

    Add a Command Response Request

    Used to add a Command Response Request. There can be maximum of 25 nodes in a single request.
    Binary data can be sent in base64 encoding with the is_base64: true flag.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Add a request to Command Response

    node_ids
    Array of strings [ 1 .. 25 ] items unique
    cmd
    integer [ 0 .. 256 ]
    data
    string <= 65536 characters
    is_base64
    boolean
    timeout
    integer [ 1 .. 2592000 ]
    override
    boolean

    Responses

    Request samples

    Content type
    application/json
    {
    • "node_ids": [
      ],
    • "cmd": 1,
    • "data": {
      },
    • "is_base64": false,
    • "timeout": 30,
    • "override": true
    }

    Response samples

    Content type
    application/json
    {
    • "request_id": "6jyMKuFuAq3gLnmStTKyBQ",
    • "status": "success"
    }

    Get the Command Response Requests

    Get the Command Response Requests for a given request id.
    You can query the command response request by either of the following ways,

    • request_id: If just request id is given then a matching single record will be returned
    • request_id and node_id: If request id along with node id is is provided then a matching single record will be returned
    • node_id with start_time and end_time: If node id along with start time and end time is provided then all requests between that time interval will be returned
    • node_id with optional cmd_id: If node id is provided then response will have all the command response requests(paginated) for input node id. Optinally you can send the cmd_id parameter to filter out the requests.
    • node_id with optional status: If node id is provided then response will have all the command response requests(paginated) for input node id. Optinally you can send the status parameter to filter out the requests.
    • status: If you just provide the status parameter then all the command response requests added by current user matching the input status will be returned

    Valid values for status parameter are requested, in_progress, success, timed_out, failure

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    request_id
    string

    ID of the command response request.

    node_id
    string

    ID of the node

    status
    string

    status of command

    start_time
    number

    Start time of the requests.

    end_time
    number

    End time of the requests.

    cmd_id
    number

    command id of command

    start_id
    string

    Used for pagination.

    num_records
    number
    Default: 10

    Used for pagination, number of records to be fetched.

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "requests": [
      ],
    • "total": 10,
    • "next_id": "some id"
    }

    Add a Command Response Request

    Used to add a Command Response Request. There can be maximum of 25 nodes in a single request.
    Binary data can be sent in base64 encoding with the is_base64: true flag.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Add a request to Command Response

    node_ids
    Array of strings [ 1 .. 25 ] items unique
    cmd
    integer [ 0 .. 256 ]
    data
    string <= 65536 characters
    is_base64
    boolean
    timeout
    integer [ 1 .. 2592000 ]
    override
    boolean

    Responses

    Request samples

    Content type
    application/json
    {
    • "node_ids": [
      ],
    • "cmd": 1,
    • "data": {
      },
    • "is_base64": false,
    • "timeout": 30,
    • "override": true
    }

    Response samples

    Content type
    application/json
    {
    • "request_id": "6jyMKuFuAq3gLnmStTKyBQ",
    • "status": "success"
    }

    API Info

    This api fetches available API endpoints and methods.

    This api fetches available API endpoints and methods.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    all_paths
    boolean
    Default: false

    When true, the response will contain all available endpoints and methods. When false, the response will contain only admin API endpoints and methods.

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Tags Service

    Admin tag management

    Get the Tags related data for various Resources

    This API is to get the tags related data for Resources.
    Querying for data can be done using {Resource Type and Resource ID}, {Tag Name and Tag Value} and {Tags and Resource Type} combinations only.

    • When Tag Name and Tag Value is passed, list of Resources is returned. Additionally Resource Type can be passed as optional query param to filter results.
    • When Resource Type and Resource ID is passed, list of Tags attached to it are returned. Additionally Tag Name can be passed as optional query param to filter results.
    • When Tags and Resource Type is passed, list of resources based on multiple tags combination is returned for the entered Resource Type.
    • When querying for Users on a particular Tag, additional_data like User's custom data, and number of mapped nodes can be returned with optional flags like custom_data and node_counts.
    Special characters in Tag Value need to be url encoded while querying the data using Tag Name and Tag Value combination.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    tag_name
    string
    Example: tag_name=esp.location

    Name of the Tag

    tag_value
    string
    Example: tag_value=Delhi

    Value of the Tag

    resource_type
    string
    Example: resource_type=Node

    Type of the Resource. i.e Node, Group, OTAImage, OTAJob, User

    resource_id
    string
    Example: resource_id=abcdefjkilmnopqrstuvwx

    UUID of the Resource

    tags
    string
    Example: tags=location:pune OR location:bangalore

    Used to fetch list of resources based on multiple tags. Tags can be combined by either AND or OR. Resource Type is required to be passed when tags are passed.

    custom_data
    boolean
    Example: custom_data=true

    Flag to return Custom_Data of the Resource. Only supported on Resource_type = User.

    num_records
    string

    Used for pagination, number of records to be fetched

    start_id
    string

    Used for pagination, Start Id of the record to be fetched

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "resources": [
      ],
    • "total": 1
    }

    Attach Tags to various Resources

    This API is used to Tag various resources like Nodes, Groups, OTA Images and OTA Jobs.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    resource_type
    required
    string
    Example: resource_type=NODE

    Used for specifying the resource type. i.e Node, Group, OTAImage or OTAJob

    resource_id
    required
    string
    Example: resource_id=abcdefjkilmnopqrstuvwx

    Used to specify UUID of the Resource to attach Tags.

    Request Body schema: application/json
    required

    Request body for attaching tags with the nodes.

    tags
    Array of strings

    Responses

    Request samples

    Content type
    application/json
    {
    • "tags": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Detach Tags to various Resources

    This API is used to remove Tags from various resources like Nodes, Groups, OTA Images and OTA Jobs.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    resource_type
    required
    string
    Example: resource_type=NODE

    Used for specifying the resource type. i.e Node, Group, OTAImage or OTAJob

    resource_id
    required
    string
    Example: resource_id=abcdefjkilmnopqrstuvwx

    Used to specify UUID of the Resource to attach Tags.

    Request Body schema: application/json
    required

    Request body for attaching tags with the nodes.

    tags
    Array of strings

    Responses

    Request samples

    Content type
    application/json
    {
    • "tags": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Get the Tag Names and Values attached to various Resources

    This API is to get the Tag Names and Values of the various tags attached to Resources.
    If no particular tag_name is passed, API will return the various Tag Names.
    If a tag_name is passed, API will return the various Tag Values.
    Additionally Resource Type can be passed to filter results.
    Special characters in Tag Value need to be url encoded while querying the data using Tag Name and Tag Value combination.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    tag_name
    string
    Example: tag_name=esp.location

    Name of the Tag

    resource_type
    string
    Example: resource_type=Node

    Type of the Resource. i.e Node, Group, OTAImage, OTAJob, User

    num_records
    string

    Used for pagination, number of records to be fetched

    start_id
    string

    Used for pagination, Start Id of the record to be fetched

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "tags": [
      ],
    • "next_id": "location",
    • "total": 5
    }

    Secure Sign

    APIs used to securely sign the OTA image with signing key and get logs of signing requests.

    API to securely sign the OTA Images(firmware) and associated bootloader files.

    This API can be used to securely sign the ota images and optionally corresponding bootloader.
    key_names accepts multiple keys. If more than one key is specified then the input image is signed with all those keys and only one output file will be generated.
    If bootloader of the OTA image is to be signed, specify sign_boot_loader true in request body.

    Note:- One can upload the firmware and bootloader compressed zip using the GET /{version}/admin/otaimage/upload_reqest and POST /{version}/admin/otaimage/upload_confirm API with image_type as package.
    - If the firmware file has been uploaded individually then bootloader can be uploaded and linked to firmware using using the GET /{version}/admin/file/upload_reqest and POST /{version}/admin/file/upload_confirm API
    - Word firmware image and ota image is used interchangeably
    Note: In private deployments, this is a SuperAdmin user API

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for Signing ota images

    One of
    ota_image_id
    required
    string

    ID of the image to be signed.

    key_names
    required
    Array of strings

    Name(s) of the key with which firmware image/bootloader file should be signed.

    sign_boot_loader
    boolean

    specify as true when bootloader file need to be signed along with OTA image file. Default is false.

    Responses

    Request samples

    Content type
    application/json
    {
    • "image_id": "image id",
    • "key_names": [
      ],
    • "sign_boot_loader": true
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Secure Signing is successful",
    • "request_id": "klwjeb"
    }

    API to get secure signing request status

    This API can be used to check the status of signing request by the input request_id
    Note: In private deployments, this is a SuperAdmin user API

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    request_id
    required
    string

    request id

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "request_id": "sejnsdn",
    • "status": "success",
    • "description": "Secure Signing is in progress"
    }

    API to get the images signed by given key.

    This API can be used to get the details of OTA images signed by the specified key.
    Note: In private deployments, this is a SuperAdmin user API

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    key_name
    string

    key_name

    num_records
    number

    num_records

    start_id
    string

    start_id

    Responses

    Response samples

    Content type
    application/json
    {
    • "keys": [
      ],
    • "images": [
      ],
    • "total": 0
    }

    API to get the keys used to sign given image.

    This API can be used to get the list of keys used to sign the input image.
    Note: In private deployments, this is a SuperAdmin user API

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    image_id
    required
    string

    image_id

    num_records
    number

    num_records

    start_id
    string

    start_id

    Responses

    Response samples

    Content type
    application/json
    {
    • "ota_image_id": "ota_image_id",
    • "signing_details": [
      ],
    • "total": 0
    }

    Key Management

    APIs used to manage keys that are used to securely sign the OTA image.

    This API creates a new key.

    This API creates a new key with given algorithm.
    Maximum allowed length for key name is 256 characters, can contain only alphanumeric characters, forward slashes (/), underscores (_), and dashes (-),
    Allowed values for specification are RSA_3072 or ECC_NIST_P256.
    Note: In private deployments, this is a SuperAdmin user API

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for creating a new key

    One of
    key_name
    required
    string
    key_spec
    required
    string
    Enum: "RSA_3072" "ECC_NIST_P256"

    Algoithm to be used to create key

    description
    string
    tags
    Array of strings

    tags to be added to the Key.

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "key_name": "key name",
    • "key_spec": "RSA_3072",
    • "description": "Some description",
    • "tags": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "successfully created key",
    • "digest": "f725cd9a53fad489e2f46eba02effee5e20379265f3ed98a71e1718c866ffaeb",
    • "key_id": "uuid"
    }

    Get details and digest of the key.

    This API can be used to get the details of the key like algorithm, digest. If key name is not specified then all the keys for current user will be returned.
    Note: In private deployments, this is a SuperAdmin user API

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    key_name
    string

    Name of the key

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    OAuth in RainMaker (For OAuth only deployments)

    APIs for OAuth 2.0 Authentication in RainMaker (Beta)

    Initiate the OAuth2 flow. (Beta)

    The user logs in by choosing the provider on the page. Returns authorization code on the redirect URI.

    query Parameters
    response_type
    required
    string

    The response type. Should be "code".

    client_id
    required
    string

    The app client ID.

    redirect_uri
    required
    string
    Example: redirect_uri=https://redirect_uri

    The redirect URI which was previously registered for the app client whose ID is provided in the client_id query parameter.

    scope
    string

    The requested scope. Currently, ignored.

    identity_provider
    string

    The identity provider to be used. It is either GOOGLE, SIGNINWITHAPPLE or the provider name in uppercase. In case of normal RainMaker, if this parameter is empty, it redirects to GITHUB.

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "string",
    • "description": "string"
    }

    Get an authorization code (Beta)

    The endpoint where the authorization server redirects the user after granting authorization. Response should be returned as either query parameter or in request body. response_modes_supported: ["query", "form_post"]

    query Parameters
    code
    string

    The authorization code from provider.

    state
    string

    The state parameter passed in the authorization request from RainMaker.

    error
    string

    If any error from provider

    Request Body schema: application/x-www-form-urlencoded
    optional
    code
    string

    The authorization code from provider.

    state
    string

    The state parameter passed in the authorization request from RainMaker.

    error
    string

    If any error from provider

    Responses

    Get authorisation tokens for user (Beta)

    The endpoint where the client exchanges the authorization code for an access token, refresh token, id token with OAuth2 flow. Or exchange refresh token for new tokens. Calls the provider token URL and then uses that information to create RainMaker tokens. These JWT authorisation tokens then can be used for other calls.

    Authorizations:
    AccessToken
    Request Body schema: application/x-www-form-urlencoded
    required
    grant_type
    required
    string
    Enum: "authorization_code" "refresh_token"

    The grant type.

    code
    string

    The authorization code obtained from the authorization endpoint. (For authorization_code grant type)

    redirect_uri
    string

    The redirect URI used in the authorization request. (For authorization_code grant type)

    client_id
    required
    string

    The client ID.

    client_secret
    string

    The corresponding client secret. Not required for public clients.

    refresh_token
    string

    The refresh token obtained previously. (For refresh_token grant type)

    wechat_token_only
    string

    All WeChat logins coming from the phone app should set this value to true.

    Responses

    Request samples

    Content type
    application/x-www-form-urlencoded
    Example
    grant_type=authorization_code&code=xxxx&redirect_uri=https%3A%2F%2Fredirect_uri&client_id=id&client_secret=secret

    Response samples

    Content type
    application/json
    {
    • "access_token": "string",
    • "token_type": "Bearer",
    • "expires_in": 0,
    • "refresh_token": "string",
    • "id_token": "string"
    }

    Custom User Data for Admins

    User specific data management for Admin users (Customer Deployments only)

    Get the Custom user data

    Fetches the custom user data of the user whose id, email or phone_number is provided in query parameters.
    Only available for Customer Deployments. Returns "Invalid Request" otherwise.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    user_id
    string

    user_id of the user whose data is to be fetched.

    user_name
    string

    User name of the user whose data is to be fetched. Example: Email - username@domain.com, Phone number - <+Mobile Number with country code>

    user_email
    string

    DEPRECATED - email of the user whose data is to be fetched, if user has used email to sign up. Example - username@domain.com

    user_phone_number
    string

    DEPRECATED - phone_number of the user whose data is to be fetched, if user has used phone_number to sign up. Example - <+Mobile Number with country code>

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "membership_info": {
      },
    • "esp.location": {
      },
    • "profile": {
      },
    • "preferences": {
      }
    }

    Store the custom User data

    To store or update the custom user data of the user whose id, email or phone_number is provided in query parameters.
    Operations on Data:

    • The data can be deleted by putting data: null.
    • If the key is already present, then the value will be replaced. Arrays will also be replaced entirely.
    • If the key is not present, then the value will be added.
    • If the value is null, then the key-value will be deleted.
    Note: The JSON size should not exceed 399 KB.
    Only available for Customer Deployments. Returns "Invalid Request" otherwise.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    user_id
    string

    user_id of the user whose data is to be updated

    user_name
    string

    User name of the user whose data is to be updated. Example: Email - username@domain.com, Phone number - <+Mobile Number with country code>

    user_email
    string

    DEPRECATED - email of the user whose data is to be fetched, if user has used email to sign up. Example - username@domain.com

    user_phone_number
    string

    DEPRECATED - phone_number of the user whose data is to be fetched, if user has used phone_number to sign up. Example - <+Mobile Number with country code>

    Request Body schema: application/json
    One of
    additional property
    object (MapItem)
    value
    object
    Array of objects

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "membership_info": {
      },
    • "esp.location": {
      },
    • "profile": {
      },
    • "preferences": {
      },
    • "demographics": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "membership_info": {
      },
    • "esp.location": {
      },
    • "profile": {
      },
    • "preferences": {
      }
    }

    External API Pass Through Service

    This API is used to fetch configurations of external API. To retrieve a specific service, provide a service ID or to obtain a list, provide the starting characters of the service name.

    Fetches external API configurations

    This API is used to fetch a list of service IDs and service names of external services.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    service_id
    string

    This parameter is used to specify the service id.

    service_name
    string

    This parameter is used to fetch service list based on starting of service name

    start_id
    string

    This parameter is used for pagination.

    num_records
    string
    Default: 30

    This parameter is used to specify number of records. Max Value = 30

    Responses

    Response samples

    Content type
    application/json
    {
    • "next_id": "string",
    • "api_config_list": [
      ]
    }

    Retrieves data from external API

    This API internally makes calls to an external API and directly returns the response without any change. If the service_id is not known, users can retrieve a list of services by calling the GET /user/passthrough/config API.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    service_id
    required
    string

    This parameter is used to specify the service id.

    query_params_json
    string
    Example: latitude=-20.348404&longitude=57.552152

    This parameter is used to pass query parameters essential for calling an external API. Query parameters should be provided in JSON format. For instance, if the external API requires latitude and longitude fields, they can be sent as follows
    {"latitude":"-20.348404","longitude":"57.552152"}

    headers_json
    string
    Example: Content-Type=application/octet-stream

    This parameter is used to provide any additional headers required for calling an external API. These headers should be formatted as a JSON structure.

    path_params_string
    string
    Example: path_params_string=/product/id

    This parameter is used to pass path parameters for external API.

    Responses

    Response samples

    Content type
    application/json
    { }

    Makes a POST request to an external API endpoint

    This API internally makes a POST request to an external API endpoint with the provided parameters. If the service_id is not known, users can retrieve a list of services by calling the GET /user/passthrough/config API.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    service_id
    required
    string

    This parameter is used to specify the service id.

    Request Body schema: application/json
    required
    query_params_json
    string

    This field is used to pass query parameter essential for calling an external API. Query parameters should be provided in JSON String format. For instance, if the external API requires latitude and longitude fields, they can be sent as follows "{"latitude":"-20.348404","longitude":"57.552152"}"

    headers_json
    string

    This field is used to provide any additional headers required for calling an external API. These headers should be formatted as a JSON String structure.

    path_params_string
    string

    This field is used to pass path parameters for external API.

    body_json
    string

    This field is used to pass request body for external API.

    Responses

    Request samples

    Content type
    application/json
    {
    • "query_params_json": "{\"latitude\":\"-20.348404\",\"longitude\":\"57.552152\"}",
    • "headers_json": "{\"Content-Type\":\"application/json\"}",
    • "path_params_string": "/product/id",
    • "body_json": "{\"latitude\":\"-20.348404\",\"longitude\":\"57.552152\"}"
    }

    Response samples

    Content type
    application/json
    { }

    User [Deprecated]

    These APIs are Deprecated. Check the APIs in the 'User Management' group above.

    Creates the new user or confirms the user

    This API creates a new user or confirms the user. If the password is specified in the request body, a new user is created and a verification code is sent to user's mail address. If the verification code is sent in the request body, the user is confirmed.

    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for creating new user or confirming the user

    One of
    user_name
    string
    password
    string [ 8 .. 256 ]

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "user_name": "username@domain.com",
    • "password": "password"
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Updates Name of the user

    This API Sets or updates the name of the user.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for updating name of the user

    name
    string

    Responses

    Request samples

    Content type
    application/json
    {
    • "name": "new name"
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Fetches the details of current user

    This API fetches user_id, user_name, super_admin flag, URL of profile picture and name of current user.

    The super_admin flag is returned only when the user is a super admin, in other cases, it will not be returned in the output.
    Also the picture_url and name are not returned in the output, if it is not set by the user.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    custom_data
    boolean
    Default: false

    When true, will fetch the custom data of the logged in user

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "user_id": "string",
    • "user_name": "string",
    • "super_admin": true,
    • "picture_url": "string",
    • "name": "string",
    • "mfa": true,
    • "phone_number": "<+Mobile Number with country code>"
    }

    Deletes user account

    This API can be used by end-users to delete his/her account. Here are the details-

    • If the 'request' query param is true, user delete request is initiated and verification code is sent to user using email or phone number.
    • If 'verification_code' query param is specified, user account is deleted.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    request
    boolean
    Default: false

    if delete user request is to be initiated, value of request param should be true.

    verification_code
    number
    Default: "<verification_code>"

    if delete user request is to be verified and user account is to be deleted, the verification code received by user should be entered as value of verification_code query param.

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Handle login or extend session request from the user

    This API will be used by the users to Login to RainMaker or to extend an existing session

    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    username and password for Login

    One of
    user_name
    string
    password
    string [ 8 .. 256 ]

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "user_name": "username@domain.com",
    • "password": "password"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "status": "success",
    • "description": "Login successful",
    • "idtoken": "idtoken",
    • "accesstoken": "accesstoken",
    • "refreshtoken": "refreshtoken"
    }

    Log out user from the session

    This API will be used by the users to Logout from Rainmaker session. If optionally refreshtoken is provided, the token is revoked.

    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    logout_all
    string
    Default: "false"

    Using this flag the user can be logged out from all sessions or only current session. The possible values are true and false.

    Request Body schema: application/json
    One of
    refreshtoken
    string

    Responses

    Request samples

    Content type
    application/json
    {
    • "refreshtoken": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Handle password change request from the user

    This api handles change password request from the user. Please note, this logs out all the existing sessions of the user.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Password change request parameters

    password
    string [ 8 .. 256 ]
    newpassword
    string [ 8 .. 256 ]

    Responses

    Request samples

    Content type
    application/json
    {
    • "password": "password",
    • "newpassword": "newpassword"
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Handle forgot password request from the user

    This api handles forgot password request from the user. Please note, this does not log out the existing sessions of the user.

    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    password change request parameters

    One of
    user_name
    string

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "user_name": "username@domain.com"
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Device grouping [Deprecated]

    This API allows the primary users to remove the sharing of groups/matter fabrics with other users.It also allows secondary users to remove their own sharing with the groups/matter fabrics.

    This API removes the sharing of Groups or matter fabrics between the users.

    This API allows the primary users to remove the sharing of groups/matter fabrics with other users.It also allows secondary users to remove their own sharing with the groups/matter fabrics.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    groups
    required
    string

    Comma separated group_ids (Example groups=group_id1,group_id2)

    user_name
    required
    string
    Example: user_name=username@domain.com

    User Name

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    User Public Profile

    Fetch a user's public profile

    This api is used to fetch a public profile of any user. If a valid user_name is mentioned in the params, then the public profile of the user belonging to the given user_name is fetched. If user_name is not given, then only the current requesting user's public profile is fetched.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    user_name
    string

    This parameter is used to specify the user_name of the user whose public profile is to be fetched.

    Responses

    Response samples

    Content type
    application/json
    {
    • "user_name": "string",
    • "profile": { }
    }

    Add a new or update an existing public profile

    This api is used to add/update the public profile of requesting user only.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json

    This API is used to create or update the public profile of the requesting user only. Profile is an object of key and value where the key will be a string, and the value can be any data type (array, object, string, number, boolean). Existing keys can be updated, deleted, or assigned new values. Special cases include:

    • Passing an empty JSON object ({}) to existing profile field or any key inside it, leaves the profile or existing key unchanged.
    • If any non-existing key is assigned as an empty ({}) json, then the key gets added with the empty json
    • Empty strings and arrays are allowed and are preserved in the profile.
    • Setting null for profile deletes the profile content, resetting it to an empty JSON object ({}).
    • Nested keys can be individually updated or removed by assigning null values.
    • If all keys of a nested json are deleted, its length is zero, then the value of the key is an empty json ({})}

    profile
    object

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "profile": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Successfully updated or added public profile"
    }