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

200

Content type

application/json

{"supported_versions": ["v1"
],
"additional_info": [{"version": "v1",
"build_info": "2.5.0-49c13afea_2024-08-26T16:04",
"release_notes": "The release notes can be accessed here: https://customer.rainmaker.espressif.com/docs/rainmaker-releases"
}
]
}

User Management

User Creation, Login, Authentication and Password management

Create or confirm a user account. The user can provide an email address or a mobile number with a country code to create an account.

This API allows creating a new user or confirming an existing user.

Creating a new user: If a password is included in the request body, a new user account is created, and a verification code is sent to the provided email address or mobile number.
Confirming a user: If a verification code is included in the request body, the user is confirmed.

Locale:

You can configure the user's language preference by including the query param: locale in the request.

Note: Emails and SMS will be sent based on the specified locale only for their respective message template types that support custom configuration.

For example:

 locale: "user_locale_value"

This query param allows the user to specify their preferred language locale for receiving emails and SMS.

Reserved value: "rm_non_branded" — This value is designated for internal use and is utilized for sending emails in a specific locale when no default email is configured for the given template type. If this value is provided, it will result in an "Invalid locale" error.
If the query param: locale is omitted or left empty, the default locale configured by the admin will be used for emails and SMS.
It is case-insensitive and all input locales will be considered in lowercase.

path Parameters

version

required

string

Default: "v1"

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

query Parameters

locale

string

Default: "no_locale"

It allows the user to specify their preferred language locale for receiving emails and SMS. It is case-insensitive and all input locales will be considered in lowercase.

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

Payload

Content type

application/json

Example

Create User

{"user_name": "username@domain.com or <+Mobile Number with country code>",
"password": "password"
}

Response samples

201
400
500

Content type

application/json

{"status": "success",
"description": "Success description"
}

Updates Name and Phone number of the user

This API allows users to set or update their name, phone number, and other fields.

Additionally, Multi-Factor Authentication (MFA) can be enabled or disabled for superadmins.

If MFA is enabled, an SMS with a verification code is sent to the superadmin's phone number after initial authentication to ensure a successful login.

Important Notes:

Phone Number Updates:
- The verification_code confirms the current phone_number.
- At any point, only one phone number can be associated with a user.
- Adding a new phone number will replace the existing one and require re-verification.
MFA Settings:
- The MFA settings will take effect from the next login onwards.
User Attribute Tags:
- Users can update User Attribute Tags on themselves.
- Users cannot remove Attribute Tags that were added by Admins.
Locale Preferences:
- Users can update their configured locale language preference for emails and SMS that support custom configuration using message templates. It is case-insensitive and all input locales will be considered in lowercase.

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

Payload

Content type

application/json

Example

Update User Name

{"name": "new name"
}

Response samples

200
400
404
500

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, locale, 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.
If locale returned is no_locale, it means user has not configured any locale and it shall receive messages that are set default by admin for all template types

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

200
500

Content type

application/json

Example

Super Admin User with MFA enabled

{"user_id": "string",
"user_name": "string",
"super_admin": true,
"picture_url": "string",
"name": "string",
"mfa": true,
"phone_number": "<+Mobile Number with country code>",
"locale": "en-us"
}

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.
locale	string Default: "empty" To give custom locale language preference and override current user's configured language locale for emails and sms of user deletion verification and confirmation. It is case-insensitive and input locale will be considered in lowercase.

Responses

Response samples

200
400
500

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

Payload

Content type

application/json

Example

User Login with password

{"user_name": "username@domain.com or +Mobile Number with country code",
"password": "password"
}

Response samples

200
400
500

Content type

application/json

Example

User Login

{"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

Payload

Content type

application/json

{"refreshtoken": "string"
}

Response samples

200
400
500

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

Payload

Content type

application/json

{"password": "password",
"newpassword": "newpassword"
}

Response samples

200
400
500

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')

query Parameters

locale

string

Default: "empty"

To give custom locale language preference and override current user's configured language locale for forgot password verification emails. It is case-insensitive and input locale will be considered in lowercase.

Request Body schema: application/json
required

password change request parameters

One of

user_name

string

Responses

Request samples

Payload

Content type

application/json

Example

Request Forgot Password

{"user_name": "username@domain.com or +Mobile Number with country code"
}

Response samples

200
400
404
500

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

200
400
500

Content type

application/json

{"nodes": "[ nodeid1, ... ]",
"node_details": [{"id": "nodeid1",
"role": "primary",
"primary": true,
"status": {"connectivity": {"connected": true,
"timestamp": 1584698464101
}
},
"config": {"node_id": "nodeid1",
"config_version": "config_version",
"devices": [{ }
],
"info": {"fw_version": "fw_version",
"name": "node_name",
"type": "node_type",
"model": "node_model"
}
},
"params": {"Light": {"brightness": 100,
"output": true
},
"Switch": {"output": true
}
},
"tags": ["esp.location:pune"
],
"is_matter": true,
"metadata": { },
"node_type": "pure_matter/rainmaker_matter/rainmaker",
"mapping_timestamp": 1697440766,
"admin_access": "READ"
}
],
"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.metadata -> null The metadata will get deleted entirely
2. metadata -> {} There will be no change in the metadata also no validation error in the input
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. metadata -> {“key”:null} Metadata JSON keys can be deleted by above syntax
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

Payload

Content type

application/json

Example

Attach tags

{"tags": ["location:pune"
]
}

Response samples

200
400
500

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

Payload

Content type

application/json

{"tags": ["location:pune"
]
}

Response samples

200
400
500

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

200
400
500

Content type

application/json

{"node_id": "nodeid1",
"config_version": "config_version",
"devices": [{ }
],
"info": {"fw_version": "fw_version",
"name": "node_name",
"type": "node_type",
"model": "node_model"
}
}

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:

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

Payload

Content type

application/json

Example

Add User Node Mapping

{"node_id": "node_id",
"secret_key": "secret_key",
"operation": "add"
}

Response samples

200
400
500

Content type

application/json

Example

Add User Node Mapping

{"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

200
400
500

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

Payload

Content type

application/json

Example

Initiate User Node Mapping Request

{ }

Response samples

200
400
500

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

Payload

Content type

application/json

Example

Verify User Node Mapping Request

{"request_id": "request_id",
"challenge_response": "challenge_response"
}

Response samples

200
400
500

Content type

application/json

{"status": "success",
"description": "Success description"
}

This API creates the sharing of Nodes between users.

This API allows

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

Payload

Content type

application/json

Example

Add User Node Sharing

{"nodes": ["node_id1"
],
"user_name": "username@domain.com",
"primary": true,
"metadata": {"devices": [{"name": "AC Switch",
"type": "esp.device.switch"
}
]
}
}

Response samples

200
400
500

Content type

application/json

Example

Add User Node Sharing

{"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

200
400
500

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

200
400
500

Content type

application/json

Example

For Secondary users

{"node_sharing": [{"node_id": "string",
"users": {"primary": ["primary_user@domain.com"
],
"secondary": ["secondary_user@domain.com"
]
},
"sources": ["NODE",
"<group_id>"
]
}
]
}

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.

To get the requests raised by primary user, with primary_user flag set as true
To get the requests received by secondary user
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

200
400
500

Content type

application/json

{"sharing_requests": [{"request_id": "<request_id>",
"request_status": "declined/pending",
"request_timestamp": 1612182919,
"node_ids": ["thing1",
"thing2"
],
"user_name": "secondary_user@domain.com",
"primary_user_name": "primary_user@domain.com",
"transfer": true,
"new_role": "secondary",
"metadata": {"devices": [{"name": "AC Switch",
"type": "esp.device.switch"
}
]
},
"next_request_id": "next_request_id",
"next_user_name": "next_user_name"
}
]
}

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

200
400
404
500

Content type

application/json

{"status": "success",
"description": "Success description"
}

This API creates the sharing of Nodes between users.

This API allows

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

Payload

Content type

application/json

Example

Add User Node Sharing

{"nodes": ["node_id1"
],
"user_name": "username@domain.com",
"primary": true,
"metadata": {"devices": [{"name": "AC Switch",
"type": "esp.device.switch"
}
]
}
}

Response samples

200
400
500

Content type

application/json

Example

Add User Node Sharing

{"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

200
400
500

Content type

application/json

{"connectivity": {"connected": true,
"timestamp": 1584698464101
}
}

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

200
404
500

Content type

application/json

Example

Node_List

{"nodes": ["thing",
"thing2"
],
"node_info": [{"node_id": "thing",
"name": "Light",
"fw_version": "1.0",
"type": "Lightbulb",
"model": "led_light",
"subtype": "LED bulb",
"project_name": "rainmaker",
"node_status": "online",
"registration_timestamp": 1688454438,
"tags": ["esp.city:pune"
],
"metadata": {"serial_no": "abc123"
},
"granted_admin_access": "READ",
"status": {"connectivity": {"connected": true,
"timestamp": 123322222
}
},
"activation_timestamp": 1234567890,
"laststatusupdate_timestamp": 1234567890,
"last_config_update_timestamp": 1234567890,
"last_activity_timestamp": 1234567890
},
{"node_id": "thing2",
"name": "Light",
"fw_version": "1.0",
"type": "Lightbulb",
"model": "led_light",
"subtype": "LED bulb",
"project_name": "rainmaker",
"node_status": "online",
"registration_timestamp": 1688454438,
"tags": ["esp.city:mumbai"
],
"metadata": {"serial_no": "xyz123"
},
"status": {"connectivity": { }
},
"activation_timestamp": 1234567890,
"laststatusupdate_timestamp": 1234567890,
"last_config_update_timestamp": 1234567890,
"last_activity_timestamp": 1234567890
}
],
"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

Payload

Content type

application/json

{"tags": ["location:pune"
]
}

Response samples

200
207
400
404
500

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

Payload

Content type

application/json

{"tags": ["location:pune"
]
}

Response samples

200
400
404
500

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

200
400
500

Content type

application/json

Example

List Of Tags

{"tags": ["esp.location",
"location"
],
"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

200
400
404
500

Content type

application/json

Example

Get nodes associated with user when no role and node_details flag specified

{"primary": {"nodes": ["node_id1"
],
"total": 3
},
"secondary": {"nodes": ["node_id2"
],
"total": 1
},
"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

Payload

Content type

application/json

Example

Single node set params - node_id in request body

[{"node_id": "string",
"payload": {"Light": {"brightness": 100,
"output": true
},
"Switch": {"output": true
}
}
}
]

Response samples

200
207
400
500

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

200
400
500

Content type

application/json

{"Light": {"brightness": 100,
"output": true
},
"Switch": {"output": true
}
}

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

Payload

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

200
400
500

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

200
400
500

Content type

application/json

Example

GetOTAImageList

{"ota_images": [{"ota_image_id": "string",
"image_name": "string",
"type": "string",
"model": "string",
"image_url": "string",
"fw_version": "string",
"upload_timestamp": 0,
"file_size": 0,
"file_md5": "string",
"archived": "bool"
}
],
"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

200
400
500

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

200
400
500

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

200
400
500

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

Payload

Content type

application/json

{"ota_image_id": "ota_image_id",
"fw_version": "1.0",
"model": "echo 2",
"type": "alexa",
"image_type": "package"
}

Response samples

200
400
500

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

Payload

Content type

application/json

Example

Create a new OTA job Upload

{"ota_job_name": "OTA Job for Alexa devices, FW version 1.0 ",
"description": "Sample Description from Admin.",
"groups": ["FFFF-FFFF"
],
"nodes": ["node_id1",
"node_id2"
],
"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": {"download_window": {"start": 0,
"end": 120
},
"validity": {"start": 1639732410,
"end": 1639991610
}
}
}

Response samples

200
400
500

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.

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.
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
If archived is provided as true, then the all ota job that are archived by the user will be returned
If all is provided as true, then all the OTA jobs created by the user are returned
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

200
400
500

Content type

application/json

Example

Default Output

{"ota_jobs": [{"ota_job_id": "string",
"ota_job_name": "string",
"ota_image_id": "string",
"description": "string",
"completed_count": 0,
"rejected_count": 0,
"delayed_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",
"nodes": ["node_id"
],
"status": "string",
"metadata": {"download_window": {"start": 0,
"end": 120
},
"validity": {"start": 1639732410,
"end": 1639991610
}
},
"stream_id": "string",
"group_query": "node_type: Light_XYZ",
"priority": 5,
"expiry_timestamp_num": 1670935398,
"force_push": true,
"ota_image_url": "string"
}
],
"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

Payload

Content type

application/json

Example

Cancel OTA job

{"ota_job_id": "ota_job_id"
}

Response samples

200
400
404
500

Content type

application/json

Example

Cancel OTA Job

{"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": ["FFFF-FFFF"
],
"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

200
400
500

Content type

application/json

{"node_ota_status": [{"node_id": "node_id",
"status": "ota_status",
"timestamp": "timestamp",
"additional_info": "additional_info"
}
],
"total": 5,
"node_groups": [{"group_id": "shi8VjiQdKhkQkqBguXqK5",
"group_name": "test_group_1"
}
],
"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

200
400
500

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

Payload

Content type

application/json

{"type": "Image type",
"image_name": "Image name",
"base64_fwimage": "base64_fwimage"
}

Response samples

200
400
500

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

200
400
500

Content type

application/json

Example

Available Ota update

{"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

Payload

Content type

application/json

{"ota_job_id": "OTA job Id",
"node_id": "node Id"
}

Response samples

200
400
500

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

200
400
404
500

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

200

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

Payload

Content type

application/json

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

Response samples

200
500

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

200
400
500

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

Payload

Content type

application/json

Example

Upload bootloader

{"file_id": "4R2sF4y4g/Y4ytXQzVdumfoTAnUVYRuB",
"description": "bootloader",
"metatdata": {"key": "value"
},
"file_type": "bootloader"
}

Response samples

200
400
500

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

200
400
500

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

Payload

Content type

application/json

{"file_id": "image/Y4ytXQzVdumfoTAnUVYRuB",
"description": "Profile pic",
"metatdata": {"key": "value"
},
"file_type": "image",
"public": false
}

Response samples

200
400
500

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

200
404
500

Content type

application/json

Example

Get File by File ID or File Name

{"file_details": [{"user_id": "user_id",
"file_id": "file_id",
"description": "file description",
"file_name": "file_name",
"entity_id": "entity_id",
"file_type": "file_type",
"file_url": "file_download_url"
}
],
"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

200
404
500

Content type

application/json

{"file_details": [{"user_id": "user_id",
"file_id": "file_id",
"description": "file description",
"metadata": "metadata",
"file_name": "file_name",
"entity_id": "entity_id",
"entity_type": "entity_type",
"file_type": "file_type",
"timestamp": "timestamp",
"s3_key": "s3_key"
}
],
"total": 0
}

IOT Endpoint

API to fetch IOT Endpoint

Fetch the IOT endpoint

This API will Get the IOT endpoint

Responses

Response samples

200
400

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:

nodes -> the list of nodes to be added to the group.
parent_group_id
description
type
node_fw_version
node_model
node_type
group_metadata
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

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

Payload

Content type

application/json

Example

Create device group with nodes

{"group_name": "group_name",
"parent_group_id": "group_id",
"type": "metadata",
"nodes": ["node_id1"
],
"description": "description",
"group_metadata": {"key": "value"
},
"custom_data": {"key": "value"
}
}

Response samples

200
400
404
500

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.

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.
The value of operation can be add or remove.
While adding or removing nodes, nodes array is required to be specified in the request body.
For updating group name, group_metadata, description,custom_data and type , the new values for these parameters need to be specified.
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

Payload

Content type

application/json

Example

Update device group

{"group_name": "group_name",
"type": "metadata",
"operation": "operation",
"nodes": ["node_id1"
],
"description": "description",
"group_metadata": {"key": "value"
},
"custom_data": {"key": "value"
}
}

Response samples

200
400
500

Content type

application/json

{"status": "success",
"description": "Success description"
}

Get admin device group

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

By Default all the groups with their sub-groups will be returned
start_id and num_records are used for pagination of groups.
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.

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

200
400
404
500

Content type

application/json

Example

Default output

{"groups": [{"group_name": "group_name",
"group_id": "group_id",
"type": "type_metadata",
"mutually_exclusive": true,
"total": "<nodes_count>",
"sub_groups": [{"group_name": "group_name",
"group_id": "group_id",
"parent_group_id": "parent_group_id",
"type": "type_metadata",
"mutually_exclusive": true,
"sub_groups": null,
"total": "<nodes_count>",
"description": "description",
"group_metadata": {"key": "value"
},
"custom_data": {"key": "value"
}
}
],
"description": "description"
}
],
"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

200
400
500

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:

nodes -> the list of nodes to be added to the group.
parent_group_id
description
group_metadata
type
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

Request body for creating new Matter Fabric.

Mandatory Parameters:

group_name
is_matter

Optional Parameters:

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
description
type
group_metadata
custom_data
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

Payload

Content type

application/json

Example

Create device group

{"group_name": "group_name",
"parent_group_id": "parent_group_id",
"type": "group_metadata",
"mutually_exclusive": true,
"nodes": ["node_id1"
],
"description": "description",
"group_metadata": {"key": "value"
},
"custom_data": {"key": "value"
}
}

Response samples

200
400
500

Content type

application/json

Example

CreateDeviceGroupResponse

{"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

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.
The value of operation can be add or remove.
While adding or removing nodes, nodes array is required to be specified in the request body.
For updating group name, description ,group_metadata, custom_data and type , the new values for these parameters need to be specified.
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. 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

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
You can convert an existing node group into the matter fabric.
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.
You can provide a Certificate Signing Request to get Noc for a user for specified matter fabric.
Confirm the node commissioning with appropriate status by providing the request id received in 'Add node to fabric' step.
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
User will no longer be associated with the matter nodes if nodes are removed from the fabric
User can specify both challenge and challenge_response in the rainmaker + matter node commissioning confirmation step as of now.challenge will be deprecated soon
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

Payload

Content type

application/json

Example

Update device group

{"group_name": "group_name",
"operation": "add/remove",
"type": "type",
"mutually_exclusive": true,
"nodes": ["node_id1"
],
"description": "description",
"group_metadata": {"key": "value"
},
"custom_data": {"key": "value"
}
}

Response samples

200
400
500

Content type

application/json

Example

Update device group

{"status": "success",
"description": "success description"
}

Get user device group

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

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
To get list of nodes in a group or for all groups, set node_list flag to true.
To get sub groups in a group or for all groups, set sub_groups flag to true.
start_id and num_records are used for pagination of groups.
When group_id is passes then details of that group will be returned.
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.

The node_details flag is applicable only when group_id or group_name is passed
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
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.
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

200
400
404
500

Content type

application/json

Example

group_id specified, node_details=false, node_list=true, sub_groups=true

{"groups": [{"group_name": "group_name",
"group_id": "group_id",
"primary": true,
"type": "type_metadata",
"mutually_exclusive": true,
"nodes": ["node1",
"node2"
],
"total": "<nodes_count>",
"custom_data": {"key": "value"
},
"sub_groups": [{"group_name": "group_name",
"group_id": "group_id",
"parent_group_id": "parent_group_id",
"type": "type_metadata",
"mutually_exclusive": true,
"nodes": ["node1"
],
"total": "<nodes_count>",
"sub_groups": null,
"description": "description"
}
],
"description": "description"
}
]
}

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

200
400
500

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

Payload

Content type

application/json

Example

Add User Group Sharing

{"groups": ["group_id1"
],
"user_name": "username@domain.com",
"primary": true,
"metadata": {"devices": [{"name": "AC Switch",
"type": "esp.device.switch"
}
]
}
}

Response samples

200
400
500

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

200
400
500

Content type

application/json

Example

sub_groups=false

{"group_sharing": [{"group_id": "string",
"mutually_exclusive": "boolean",
"users": {"primary": ["primary_user@domain.com"
],
"secondary": ["secondary_user@domain.com"
]
}
}
]
}

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.

To get the requests raised by primary user, with primary_user flag set as true
To get the requests received by secondary user
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

200
400
500

Content type

application/json

{"sharing_requests": [{"request_id": "<request_id>",
"request_status": "declined/pending",
"request_timestamp": 1612182919,
"group_ids": ["group1",
"group2"
],
"group_names": ["group_name1",
"group_name2"
],
"user_name": "secondary_user@domain.com",
"primary_user_name": "primary_user@domain.com",
"transfer": true,
"new_role": "secondary",
"metadata": {"devices": [{"name": "AC Switch",
"type": "esp.device.switch"
}
]
}
}
],
"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

200
400
404
500

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

Payload

Content type

application/json

{"accept": true,
"request_id": "request_id"
}

Response samples

200
400
500

Content type

application/json

Example

Accept or Decline Sharing request for device group

{"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

200
400
500

Content type

application/json

{"fabric_node_acl": [{"group_id": "<group_id>",
"fabric_id": "<fabric_id>",
"type_entity": "NODE_ACL_OPERATE_<MatterNodeId>",
"sequence": 1,
"value": ["<group_cat_id_admin>",
"<matter_user_id>"
],
"last_modified_time": "timestamp"
}
]
}

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.

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

Aggregates supported by different data types:

float - All
int - All
bool - raw, latest, count
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

200
400
500

Content type

application/json

Example

Raw Data

{"ts_data": [{"node_id": "node_id",
"params": [{"param_name": "temperature",
"values": [{"ts": 1628557200,
"val": 2
},
{"ts": 1628560800,
"val": -3
}
],
"num_records": 2
}
],
"next_id": "string",
"aggregate": "raw",
"timezone": "Asia/Calcutta",
"differential": true,
"reset_on_negative": false
}
]
}

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.

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

Aggregates supported by different data types:

float - All
int - All
bool - raw, latest, count
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

200
400
500

Content type

application/json

Example

Raw Data

{"ts_data": [{"node_id": "node_id",
"params": [{"param_name": "temperature",
"values": [{"ts": 1628557200,
"val": 2
},
{"ts": 1628560800,
"val": -3
}
],
"num_records": 2
}
],
"next_id": "string",
"aggregate": "raw",
"timezone": "Asia/Calcutta",
"differential": true,
"reset_on_negative": false
}
]
}

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

200
400
500

Content type

application/json

{"ts_data": [{"node_id": "node_id",
"params": [{"param_name": "temperature",
"values": [{"ts": 1628557200,
"val": 35.3
},
{"ts": 1628560800,
"val": 35.7
}
],
"num_records": 2
}
],
"next_id": "string"
}
]
}

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

200
400
500

Content type

application/json

{"ts_data": [{"node_id": "node_id",
"params": [{"param_name": "temperature",
"values": [{"ts": 1628557200,
"val": 35.3
},
{"ts": 1628560800,
"val": 35.7
}
],
"num_records": 2
}
],
"next_id": "string"
}
]
}

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

200
400
500

Content type

application/json

Example

Get custom user data

{"membership_info": {"value": {"premium": false
}
},
"esp.location": {"value": {"esp.city": "Pune",
"esp.longitude": "xx.xxxx",
"esp.latitude": "xx.xxxx",
"esp.state": "Maharashtra"
},
"perms": [{"read": ["user",
"admin"
]
}
]
},
"profile": {"value": {"age": 61,
"gender": "female"
}
},
"preferences": {"perms": [{"read": ["user",
"admin"
]
},
{"write": ["user"
]
}
]
}
}

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

Payload

Content type

application/json

Example

Set custom data

{"membership_info": {"value": {"premium": true
},
"perms": [{"read": ["user",
"admin"
]
},
{"write": ["admin"
]
}
]
},
"esp.location": {"value": {"esp.city": "Pune",
"esp.longitude": "xx.xxxx",
"esp.latitude": "xx.xxxx",
"esp.state": "Maharashtra"
},
"perms": [{"read": ["user",
"admin"
]
}
]
},
"profile": {"value": {"name": "FirstName Lastname",
"age": 60
}
},
"preferences": {"value": {"theme": "dark"
},
"perms": [{"read": ["user",
"admin"
]
},
{"write": ["user"
]
}
]
},
"demographics": {"value": {"origin": "Asian",
"Languages": ["English"
]
}
}
}

Response samples

200
400
500

Content type

application/json

{"membership_info": {"value": {"premium": false
}
},
"esp.location": {"value": {"esp.city": "Pune",
"esp.longitude": "xx.xxxx",
"esp.latitude": "xx.xxxx",
"esp.state": "Maharashtra"
},
"perms": [{"read": ["user",
"admin"
]
}
]
},
"profile": {"value": {"age": 61,
"gender": "female"
}
},
"preferences": {"perms": [{"read": ["user",
"admin"
]
},
{"write": ["user"
]
}
]
}
}

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

200
400
520

Content type

application/json

{"webhook_user_node_integrations": [{"webhook_name": "test_webhook212",
"enabled": true,
"nodes_list": ["asd"
],
"events": [{"event_name": "test_event",
"event_active_timestamp": 1626684122
}
],
"active_timestamp": 1626684122
}
]
}

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

Payload

Content type

application/json

{"webhook_name": "test_webhook212",
"enabled": true,
"nodes_list": ["asd"
],
"events": [{"event_name": "test_event",
"event_active_timestamp": 1626684122
}
],
"active_timestamp": 1626684122
}

Response samples

200
400
520

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

Payload

Content type

application/json

{"webhook_name": "test_webhook212",
"enabled": true,
"nodes_list": ["asd"
],
"events": [{"event_name": "test_event",
"event_active_timestamp": 1626684122
}
],
"active_timestamp": 1626684122
}

Response samples

200
400
520

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

200
400
520

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_added	system.rmaker.event.user_node_added
o User Node Removed	rmaker.event.user_node_removed	system.rmaker.event.user_node_removed
o Node Shared with User	rmaker.event.user_node_sharing_add	system.rmaker.event.user_node_sharing_add
o Node Connected	rmaker.event.node_connected	system.rmaker.event.node_connected
o Node Disconnected	rmaker.event.node_disconnected	system.rmaker.event.node_disconnected
o Node params change	rmaker.event.node_params_changed	system.rmaker.event.node_params_changed
o Node Automation Trigger	rmaker.event.node_automation_trigger	system.rmaker.event.node_automation_trigger
o Group Shared with User	rmaker.event.user_node_group_sharing_add	system.rmaker.event.user_node_group_sharing_add
o Group added	rmaker.event.user_node_group_added	system.rmaker.event.user_node_group_added
o Group removed	rmaker.event.user_node_group_removed	system.rmaker.event.user_node_group_removed
o Node alerts	rmaker.event.alert	system.rmaker.event.alert
o Node config changed	rmaker.event.node_config_changed	system.rmaker.event.node_config_changed
o User approval OTA available	rmaker.event.user_node_ota	system.rmaker.event.user_node_ota
o Node time series data	rmaker.event.node_ts_data	system.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

Payload

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": ["google_home_graph",
"salesforce"
]
}

Response samples

200
400
500

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_added	system.rmaker.event.user_node_added
o User Node Removed	rmaker.event.user_node_removed	system.rmaker.event.user_node_removed
o Node Shared with User	rmaker.event.user_node_sharing_add	system.rmaker.event.user_node_sharing_add
o Node Connected	rmaker.event.node_connected	system.rmaker.event.node_connected
o Node Disconnected	rmaker.event.node_disconnected	system.rmaker.event.node_disconnected
o Node params change	rmaker.event.node_params_changed	system.rmaker.event.node_params_changed
o Node Automation Trigger	rmaker.event.node_automation_trigger	system.rmaker.event.node_automation_trigger
o Group Shared with User	rmaker.event.user_node_group_sharing_add	system.rmaker.event.user_node_group_sharing_add
o Group added	rmaker.event.user_node_group_added	system.rmaker.event.user_node_group_added
o Group removed	rmaker.event.user_node_group_removed	system.rmaker.event.user_node_group_removed
o Node alerts	rmaker.event.alert	system.rmaker.event.alert
o Node config changed	rmaker.event.node_config_changed	system.rmaker.event.node_config_changed
o User approval OTA available	rmaker.event.user_node_ota	system.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

Payload

Content type

application/json

Example

Enabling/Disabling an Integration

{"event_type": "rmaker.event.node_connected",
"entity_id": "system.rmaker.event.node_connected",
"entity_type": "System",
"enabled": "true/false",
"enabled_for_integrations": ["mobile_push_notification"
]
}

Response samples

200
400
500

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

200
400
500

Content type

application/json

Example

Passing event_type

{"event_entity_mapping_list": [{"event_type": "example_event_type",
"entity_id": "thing",
"entity_type": "NODE",
"enabled": false,
"enabled_for_integrations": ["google_home_graph",
"salesforce"
]
},
{"event_type": "example_event_type",
"entity_id": "system.example_event_type",
"entity_type": "SYSTEM",
"enabled": false,
"enabled_for_integrations": ["mobile_push_notification"
]
}
],
"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"
"entity_type": "System"
}

Authorizations:

AccessToken

path Parameters

version

required

string

Default: "v1"

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

Responses

Response samples

200
400
500

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

Payload

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": ["google_home_graph",
"salesforce"
]
}

Response samples

200
400
500

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

Payload

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": ["google_home_graph",
"salesforce"
]
}

Response samples

200
400
500

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

200
400
500

Content type

application/json

Example

Passing event_type

{"event_entity_mapping_list": [{"event_type": "example_event_type",
"entity_id": "thing",
"entity_type": "NODE",
"enabled": false,
"enabled_for_integrations": ["google_home_graph",
"salesforce"
]
},
{"event_type": "example_event_type",
"entity_id": "system.example_event_type",
"entity_type": "SYSTEM",
"enabled": false,
"enabled_for_integrations": ["mobile_push_notification"
]
}
],
"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

200
400
500

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

Payload

Content type

application/json

{"platform": "GCM",
"mobile_device_token": "<device token>",
"platform_type": "huawei"
}

Response samples

201
400
500

Content type

application/json

{"status": "success",
"platform_endpoint_arn": "platform endpoint arn"
}

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

200
500

Content type

application/json

{"platform_endpoints": [{"mobile_device_token": "mobile device token",
"platform_endpoint_arn": "platform endpoint arn",
"platform_application_arn": "platform application arn "
}
]
}

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

200
400
500

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

Payload

Content type

application/json

Example

Add Automation Trigger

{"name": "automation_name",
"node_id": "node_id",
"event_type": "node_params",
"metadata": "metadata",
"events": [{"params": {"Light": {"Brightness": 100
}
},
"check": "=="
}
],
"event_operator": "and",
"actions": [{"node_id": "node_id",
"params": {"Light": {"Output": true
}
}
}
],
"retrigger": false
}

Response samples

200
400
403
500

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

Payload

Content type

application/json

Example

Update Automation trigger

{"name": "<automation_name>",
"enabled": false,
"events": [{"params": {"Light": {"Brightness": 100
}
},
"check": "=="
}
],
"event_operator": "and",
"actions": [{"node_id": "<node_id>",
"params": {"Light": {"Output": true
}
}
}
],
"retrigger": false
}

Response samples

200
400
403
500

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

200
400

Content type

application/json

Example

AutomationTrigger

{"automation_name": "automation_name",
"automation_id": "automation_id",
"enabled": "true",
"node_id": "node_id",
"event_type": "event_type",
"metadata": "metadata",
"events": [{"params": { },
"check": "operator"
}
],
"event_operator": "event_operator",
"actions": [{"node_id": "node_id",
"params": { }
}
],
"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

200
400

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

Payload

Content type

application/json

{"policy_name": "<policy_name>",
"policy_json": {"version": "1.0.0",
"filters": [{"type": "nodes",
"rules": {"tags": ["location:pune",
"location:mumbai"
],
"type": ["led_light",
"switch"
]
}
}
],
"statement": [{"Effect": "Allow",
"Action": ["api:Get"
],
"Resource": ["/v1/admin/otaimage"
]
}
]
}
}

Response samples

200
400

Content type

application/json

{"status": "success",
"description": "Success description"
}

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

Payload

Content type

application/json

{"policy_json": {"version": "1.0.0",
"filters": [{"type": "nodes",
"rules": {"tags": ["location:pune",
"location:mumbai"
],
"type": ["led_light",
"switch"
]
}
}
],
"statement": [{"Effect": "Allow",
"Action": ["api:Get"
],
"Resource": ["/admin/otaimage"
]
}
]
}
}

Response samples

200
400

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

200
400

Content type

application/json

{"policies": [{"policy_name": "string",
"policy_json": {"version": "1.0.0",
"filters": [{"type": "string",
"rules": {"tags": ["string"
],
"type": ["string"
]
}
}
],
"statement": [{"effect": "allow",
"action": ["string"
],
"resource": ["string"
]
}
]
}
}
]
}

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

200
400

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

Payload

Content type

application/json

{"role_name": "<role_name>",
"policies": ["<policy_name>"
],
"role_level": 1
}

Response samples

200
400

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

Payload

Content type

application/json

{"policies": ["<policy_name1>",
"<policy_name2>"
],
"role_level": 2
}

Response samples

200
400

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

200
400

Content type

application/json

{"roles": [{"role_name": "string",
"policies": ["string"
],
"role_level": 1
}
]
}

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

200
400

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.

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

Payload

Content type

application/json

{"roles": ["role_name1",
"role_name2"
]
}

Response samples

200
400

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

200
400

Content type

application/json

Example

Get Roles for user

{"roles": ["role_name1",
"role_name2"
]
}

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
desc_order	boolean Default: true sort the response in descending order
start_id	string Used for pagination.
num_records	number Default: 10 Used for pagination, number of records to be fetched.

Responses

Response samples

200
400
500

Content type

application/json

Example

Response Data is JSON

{"requests": [{"request_id": "<short uuid> Ex: 6jyMKuFuAq3gLnmStTKyBQ",
"status": "failure",
"device_status": 4,
"status_description": "command not found",
"request_data": {"brightness": 100
},
"response_data": {"status": "successfully executed"
},
"node_id": "6jyMKuFuAq3gLnmStTKyBQ",
"request_timestamp": 1234567890,
"response_timestamp": 1234567890,
"expiration_timestamp": 1234567890,
"cmd": 1
}
],
"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.
The value of cmd should be in the range of 0 to 65535.

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 .. 65535 ]
data	string <= 65536 characters
is_base64	boolean
timeout	integer [ 1 .. 2592000 ]
override	boolean

Responses

Request samples

Payload

Content type

application/json

{"node_ids": ["6jyMKuFuAq3gLnmStTKyBQ"
],
"cmd": 1,
"data": {"brightness": 10
},
"is_base64": false,
"timeout": 30,
"override": true
}

Response samples

200
207
400
500

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
desc_order	boolean Default: true sort the response in descending order
start_id	string Used for pagination.
num_records	number Default: 10 Used for pagination, number of records to be fetched.

Responses

Response samples

200
400
500

Content type

application/json

Example

Response Data is JSON

{"requests": [{"request_id": "<short uuid> Ex: 6jyMKuFuAq3gLnmStTKyBQ",
"status": "failure",
"device_status": 4,
"status_description": "command not found",
"request_data": {"brightness": 100
},
"response_data": {"status": "successfully executed"
},
"node_id": "6jyMKuFuAq3gLnmStTKyBQ",
"request_timestamp": 1234567890,
"response_timestamp": 1234567890,
"expiration_timestamp": 1234567890,
"cmd": 1
}
],
"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 .. 65535 ]
data	string <= 65536 characters
is_base64	boolean
timeout	integer [ 1 .. 2592000 ]
override	boolean

Responses

Request samples

Payload

Content type

application/json

{"node_ids": ["6jyMKuFuAq3gLnmStTKyBQ"
],
"cmd": 1,
"data": {"brightness": 10
},
"is_base64": false,
"timeout": 30,
"override": true
}

Response samples

200
207
400
500

Content type

application/json

{"request_id": "6jyMKuFuAq3gLnmStTKyBQ",
"status": "success"
}

API Info

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

200

Content type

application/json

[{"path": "/{version}/user",
"methods": ["GET",
"POST",
"PUT",
"DELETE"
]
}
]

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} 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 only Tags are passed, list of resources based on multiple tags combination is returned. Additionally Resource Type can be passed as optional query param to filter results.
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

200
400
500

Content type

application/json

Example

When Tag is passed

{"resources": [{"tenant_id": "*",
"resource_type": "NODE",
"resource_id": "abcdefjkilmnopqrstuvwx",
"resource_admin_id": "fgsdfgsdfg-5dfsghefty-5634567-dhfgh"
}
],
"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

Payload

Content type

application/json

{"tags": ["location:pune"
]
}

Response samples

200
400
500

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

Payload

Content type

application/json

{"tags": ["location:pune"
]
}

Response samples

200
400
500

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

200
400
500

Content type

application/json

Example

List Of Tag Names

{"tags": ["esp.location",
"location"
],
"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

Payload

Content type

application/json

{"image_id": "image id",
"key_names": ["Light_Key",
"Grill_Key"
],
"sign_boot_loader": true
}

Response samples

200
400
500

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

200
400
500

Content type

application/json

Example

Signing request status in progress

{"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

200
400
404
500

Content type

application/json

{"keys": [{"key_name": "key_name",
"public_key_digest": "public_key_digest"
}
],
"images": [{"image_id": "image_id",
"signed_image_url": "signed_image_url",
"signed_image_id": "signed_image_id",
"user_id": "user_id",
"timestamp": 1708430640834644200,
"file_type": "SECURELY_SIGNED_FIRMWARE/SECURELY_SIGNED_BOOTLOADER"
}
],
"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

200
400
500

Content type

application/json

{"ota_image_id": "ota_image_id",
"signing_details": [{"keys": [{"key_name": "key_name",
"public_key_digest": "public_key_digest"
}
],
"signed_image_url": "“signed_image_url",
"signed_image_file_id": "ota_image/image_id/random_is",
"timestamp": 1687436667589778700,
"user_id": "some user id",
"file_type": "SECURELY_SIGNED_FIRMWARE"
}
],
"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

Payload

Content type

application/json

Example

Create RSA key

{"key_name": "key name",
"key_spec": "RSA_3072",
"description": "Some description",
"tags": ["key:val"
]
}

Response samples

200
400
500

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

200
400
404
500

Content type

application/json

[{"key_name": "string",
"key_id": "string",
"key_spec": "string",
"description": "description",
"public_key": "public key PEM string",
"private_key": "private key PEM string",
"public_key_sha256_digest": "string",
"creation_timestamp": 0
}
]

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 Value: "code" 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 required	string The identity provider to be used. It is either GOOGLE, SIGNINWITHAPPLE or the provider name in uppercase.

Responses

Response samples

500

Content type

application/json

{"status": "string",
"description": "string"
}

Send code (Internal)

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. Required if no error.
state	string The state parameter passed in the authorization request from RainMaker. Required if no error.
error	string If any error from provider

Request Body schema: application/x-www-form-urlencoded
optional

code	string The authorization code from provider. Required if no error.
state	string The state parameter passed in the authorization request from RainMaker. Required if no error.
error	string If any error from provider

Responses

Send code (Internal)

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. Required if no error.
state	string The state parameter passed in the authorization request from RainMaker. Required if no error.
error	string If any error from provider

Request Body schema: application/x-www-form-urlencoded
optional

code	string The authorization code from provider. Required if no error.
state	string The state parameter passed in the authorization request from RainMaker. Required if no error.
error	string If any error from provider

Responses

Get authorisation tokens for user (Beta)

The endpoint where the client exchanges the authorization code or username, password 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:

ClientSecretBasic

Request Body schema: application/x-www-form-urlencoded
required

grant_type required	string Enum: "authorization_code" "password" "refresh_token" The grant type.
client_id	string The client ID. Required if client_secret_post.
client_secret	string The corresponding client secret. Not required for public clients. Required if client_secret_post.
code	string The authorization code obtained from the authorization endpoint. Required if authorization_code grant type
redirect_uri	string The redirect URI used in the authorization request. Required if authorization_code grant type.
refresh_token	string The refresh token obtained previously. Required if refresh_token grant.
identity_provider	string The identity provider. Required if password grant.
username	string The username. Required if password grant.
password	string The password. Required if password grant.
wechat_token_only	string All WeChat logins coming from the phone app should set this value to true.
locale	string It allows the user to specify their preferred language locale for receiving emails and SMS. It is case-insensitive and input locale will be considered in lowercase.

Responses

Request samples

Payload

Content type

application/x-www-form-urlencoded

Example

Exchange auth code with tokens

grant_type=authorization_code&code=xxxx&redirect_uri=https%3A%2F%2Fredirect_uri&client_id=id&client_secret=secret

Response samples

200
400

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

200
400
500

Content type

application/json

Example

Get custom user data

{"membership_info": {"value": {"premium": false
}
},
"esp.location": {"value": {"esp.city": "Pune",
"esp.longitude": "xx.xxxx",
"esp.latitude": "xx.xxxx",
"esp.state": "Maharashtra"
},
"perms": [{"read": ["user",
"admin"
]
}
]
},
"profile": {"value": {"age": 61,
"gender": "female"
}
},
"preferences": {"perms": [{"read": ["user",
"admin"
]
},
{"write": ["user"
]
}
]
}
}

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

Payload

Content type

application/json

Example

Set custom data

{"membership_info": {"value": {"premium": true
},
"perms": [{"read": ["user",
"admin"
]
},
{"write": ["admin"
]
}
]
},
"esp.location": {"value": {"esp.city": "Pune",
"esp.longitude": "xx.xxxx",
"esp.latitude": "xx.xxxx",
"esp.state": "Maharashtra"
},
"perms": [{"read": ["user",
"admin"
]
}
]
},
"profile": {"value": {"name": "FirstName Lastname",
"age": 60
}
},
"preferences": {"value": {"theme": "dark"
},
"perms": [{"read": ["user",
"admin"
]
},
{"write": ["user"
]
}
]
},
"demographics": {"value": {"origin": "Asian",
"Languages": ["English"
]
}
}
}

Response samples

200
400
500

Content type

application/json

{"membership_info": {"value": {"premium": false
}
},
"esp.location": {"value": {"esp.city": "Pune",
"esp.longitude": "xx.xxxx",
"esp.latitude": "xx.xxxx",
"esp.state": "Maharashtra"
},
"perms": [{"read": ["user",
"admin"
]
}
]
},
"profile": {"value": {"age": 61,
"gender": "female"
}
},
"preferences": {"perms": [{"read": ["user",
"admin"
]
},
{"write": ["user"
]
}
]
}
}

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

200
400
500

Content type

application/json

{"next_id": "string",
"api_config_list": [{"service_id": "string",
"service_name": "string"
}
]
}

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

200
400
500

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

Payload

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

200
400
500

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

Payload

Content type

application/json

Example

Create User

{"user_name": "username@domain.com",
"password": "password"
}

Response samples

201
400
500

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

Payload

Content type

application/json

{"name": "new name"
}

Response samples

200
400
404
500

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

200
500

Content type

application/json

Example

Super Admin User with MFA enabled

{"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

200
400
500

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

Payload

Content type

application/json

Example

User Login

{"user_name": "username@domain.com",
"password": "password"
}

Response samples

200
400
500

Content type

application/json

Example

User Login

{"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

Payload

Content type

application/json

{"refreshtoken": "string"
}

Response samples

200
400
500

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

Payload

Content type

application/json

{"password": "password",
"newpassword": "newpassword"
}

Response samples

200
400
500

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

Payload

Content type

application/json

Example

Request Forgot Password

{"user_name": "username@domain.com"
}

Response samples

200
400
404
500

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

200
400
500

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

200
404
500

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

Payload

Content type

application/json

Example

Add a public profile

{"profile": {"key1": "value1",
"key2": "value2"
}
}

Response samples

200
400
404
500

Content type

application/json

{"status": "success",
"description": "Successfully updated or added public profile"
}

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

API Versions

Get supported API versions

Responses

Response samples

User Management

Create or confirm a user account. The user can provide an email address or a mobile number with a country code to create an account.

Locale:

Note: Emails and SMS will be sent based on the specified locale only for their respective message template types that support custom configuration.

path Parameters

query Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Updates Name and Phone number of the user

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Fetches the details of current user

Authorizations:

path Parameters

query Parameters

Responses

Response samples

Deletes user account

Authorizations:

path Parameters

query Parameters

Responses

Response samples

Handle login or extend session request from the user

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Log out user from the session

Authorizations:

path Parameters

query Parameters

Request Body schema: application/json

Responses

Request samples

Response samples

Handle password change request from the user

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Handle forgot password request from the user

path Parameters

query Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

User Node Association

Get the nodes associated with the user

Authorizations:

path Parameters

query Parameters

Responses

Response samples

Add tags to Node or update the metadata

Authorizations:

path Parameters

query Parameters

Request Body schema: application/jsonoptional

Responses

Request samples

Response samples

Delete tags from Node

Authorizations:

path Parameters

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
optional

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required