Ctrl + F on a Windows, is the keyboard shortcut for quick search.
Command+F on a Mac, is the keyboard shortcut for quick search.
Overview
Gizwits is an open IoT device management platform that provides enterprise and individual developers with services such as fast device onboarding, provisioning, authentication, configuration, remote monitoring, task scheduling, and advanced data analytics.
Gizwits exposes a significant range of functionality via Open API.
The Open API lets developers securely authenticate users with custom applications so they can control the Gizwits powered devices associated with their accounts.
APIs
The following are several sets of API lists that specify the structure of the data that is exchanged between your applications and the Gizwits Cloud.
User Management：Manage user registration, login, password reset etc.
API List
Description
get_app_users
Get user information
post_app_users
Create a new user
put_app_users
Update user information
post_app_login
User login
post_app_request_token
Request an access token
post_app_reset_password
Request to password reset
post_app_sms_code
Get and verify a SMS verification code
get_app_verify_codes
Get an image verification code
post_app_verify_codes
Verify an image verification code
put_app_verify_codes
Verify a SMS verification code
Message Center：Get, mark as read and delete system messages etc.
API List
Description
get_app_messages
Get a message list
put_app_messages
Mark as read or delete a message
Binding Management：Bind/unbind user and devices.
API List
Description
post_app_bind_mac
Bind a device by its MAC address
delete_app_bindings
Unbind devices
get_app_bindings
Get a list of bound devices
post_app_bind_latest
Bind a device by its QRCode
put_app_bindings_did
Update binding information
get_app_did_bindings
Get guest users information for a given device
Device Remote Monitoring: Get device current status, reported raw data, online&offline status records, and control it remotely etc.
API List
Description
get_app_devdata_did_latest
Get latest status of a given device
get_app_datapoint
Get the definition of product datapoint
get_app_devices_did
Get details of a given device
get_app_devices_did_raw_data
Get communication log and online&offline status records of a device
post_app_control_did
Control a given device remotely
Device Sharing: Users share their own bound device to other users to bind, and unbind other users’ binding to their own devices, etc.
API List
Description
get_app_sharing
Get a list of sent and received sharing invitations
post_app_sharing
Create a sharing invitation
delete_app_sharing_id
Cancel/retract a sharing invitation
put_app_sharing_id
Accept/reject a sharing invitation
get_app_sharing_code
Get sharing invitation information of a given QRCode
post_app_sharing_code
Accept a sharing invitation by a given QRCode
put_app_sharing_idalias
Update a guest or owner alias of a given invitation
post_app_sharing_did_transfer
Transfer ownership of a device to a guest
Device Grouping: Group multiple devices so that send an instruction to control multiple devices incoming a group at once.
API List
Description
get_app_group
Get all user groups
post_app_group
Create a group
delete_app_group_id
Delete a device group
put_app_group_id
Update group information
get_app_group_id_devices
Get devices information of a given group
post_app_group_id_devices
Add devices into a group
delete_app_group_id_devices
Remove devices from a group
post_app_group_id_control
Control all devices in a given group
Devices Linkage: Set up rules of devices linkage that will be triggered by some devices to control other devices.
API List
Description
get_app_rules_params
Get datapoints of all products can be used by rules
get_app_rules
Get rules list for devices linkage
post_app_rules
Create a rule of devices linkage
delete_app_rules
Delete a rule of devices linkage
put_app_rules
Update a rule of devices linkage
User Scenario: Predefine a series of device actions according to a scenario that will be triggered when needed.
API List
Description
get_app_scene
Get all scenarios
post_app_scene
Create a scenario
delete_app_scene_id
Delete a scenario
put_app_scene_id
Update a scenario information
get_app_scene_id_task
Get task execution status of a given scenario
post_app_scene_id_task
Perform a scenario task
Task Scheduling Management: Addition, deletion, modification, etc. of device task scheduling.
API List
Description
get_app_devices_scheduler
Get a list of scheduled tasks
post_app_devices_scheduler
Create a scheduled task
delete_app_devices_scheduler
Delete a scheduled task
put_app_devices_scheduler
Update a scheduled task
Common Task Scheduling: Schedule tasks for individual devices, device groups, and scenarios.
API List
Description
get_app_common_scheduler
Get a common scheduled task
post_app_common_scheduler
Create a common scheduled task
delete_app_common_scheduler
Delete a common scheduled task
put_app_common_scheduler
Update a common scheduled task
Advanced Data API: Retrieve aggregated values of daily maximum, average, etc. for the numeric data reported by devices.
API List
Description
get_app_bindings
Get an aggregated value of a given device
System Information: Check the current version of Open API and retrieve a list of all possible errors.
API List
Description
get_status
Get service status
get_errors
Get error status code list
Specification
Using HTTP API
Gizwits Open API exposes a significant range of functionality via a RESTful API set, which can be accessed via any client using standard HTTP.
Recommended HTTP Clients：
GUI client PostMan
Command-line client curl
HTTP Request Headers
X-Gizwits-Application-Id
X-Gizwits-Application-Id referred to as AppID, is a unique identifier applied to the Gizwits platform. When issuing a HTTP request, your request must include this header parameters.
On the product page of the developer center, click the “Application Configuration” menu in the left column to create an application and get an AppID as well:
X-Gizwits-User-token
X-Gizwits-User-token referred to as UserToken, represents the user context during the API interaction.
UserToken has a validity period. By default, it expires after 7 days.
UserToken can be obtained through user registration or login request. UserToken is the token field returned in the response, and expire_at field is the timestamp of UserToken expiration:
Select md5, 32 bits [small] for encryption, fill in product_secret and X-Gizwits-Timestamp, without the “+” sign, as shown below
Online debugger
We provide online API debugging tools. The corresponding debug link is given in each API description.
The following example illustrates the usage of API debugging tools via user login:
Click user login to enter the API debugging page
There is a red exclamation mark on the right side of the API. After clicking it, a dialog box pops up prompting for the required header information.
The API needs to enter the X-Gizwits-Application-Id, get the AppID according to the previous instructions and fill it in, click “Authorize” to authorize
The page is automatically refreshed and the exclamation mark turns blue, indicating that the required header information has been filled in (filled does not necessarily indicate that the value is correct. If the value is incorrect, the corresponding result will be returned in the response)
Enter the parameter value in the input box (click the Example Value yellow box to the right of the parameter to enter the sample JSON quickly)
Click the “Try” button to complete the API request
The request completes, displaying the equivalent curl statement of local call, request URL, response body, response code, and response header
User Management
Create a user
Debug console
There are several ways to create new users:
Anonymous registration, creating a user with a unique phone_id
User name&password registration, create a user by username and passowrd
Mobile phone registration, create users via phone, password and code (SMS verification code). About SMS verification code acquisition, please refer to the following section.
Email registration, create users via email and password
Third-party authentication, creating a user through src, uid, and token in authData. Currently supports Tencent QQ, Sina Weibo, Baidu, WeChat, Facebook, Twitter, Google+, Amazon
Third-party authentication notes:
For Google and Amazon third-party authentication, token in authData needs to start with “Bearer”
For QQ and Twitter third-party authentication, it needs to fill API_KEY and API_Secret in Developer Center
Facebook, Twitter, Google, Amazon third-party authentication can only be used in the Eastern United States and Europe regions
Password strength requirements:
The password length is not less than 8 characters
The password should be combination of three of four types of characters, which are uppercase, lowercase, numbers, special symbols
Request method and URL
1 2
POST http://api.gizwits.com/app/users
Request paramters
Params
Data Type
Required
Param Type
Description
X-Gizwits-Application-Id
string
Yes
header
appid
phone_id
string
No
body
Anonymous identity, the request parameter for anonymous registration
username
string
No
body
User name, the request parameter for user name&password registration
password
string
No
body
Password, the request parameter for username&password registration, mobile registration, email registration
email
string
No
body
Email Address, the Request Parameter for Email registration
phone
string
No
body
Mobile phone number, the request parameter for mobile phone registration
code
string
No
body
Verification code, SMS verification code, request parameter for mobile registration
lang
string
No
body
Language:en,zh-cn
src
string
No
body
Platform type: qq, sina, baidu, wechat, twitter, facebook, google, amazon
uid
string
No
body
returned uid from third-party authentication platform
token
string
No
body
returned token from third-party authentication platform
The token parameter obtained by the API is mainly used as a request parameter when the SMS verification code API and the image verification code API are invoked.
Only those users who have set email or phone can reset the password.
Reset your password via email, just provide email, password reset link is sent to the email address
Reset the password via phone, provide phone number, new_pwd, code (returned by calling get SMS verification code API)
Request method and URL
1 2
POST http://api.gizwits.com/app/reset_password
Request paramters
Params
Data Type
Required
Param Type
Description
X-Gizwits-Application-Id
string
Yes
header
appid
email
string
No
body
Registered e-mail
phone
string
No
body
Registered phone number
new_pwd
string
No
body
New password
code
string
No
body
Verification code
Response Parameters
No
Get and verify a SMS verification code
Debug console
The main uses of the SMS verification code are:
Registration for mobile phone user
Password reset for mobile phone user
Other sensitive actions that you think require a SMS verification code The API can obtain and verify the verification code:
Obtaining SMS verification code only needs phone number
Verifying SMS verification code needs phone number and code
About foreign mobile phone number
To send a SMS verification code to a foreign mobile phone number, follow the format: +{country code}{mobile phone number}. Assume that an U.S. phone number (country code is 1) is 4246531234, then the phone should be filled as “+14246531234”
The list of country codes can be obtained here.
The SMS verification code is invalid immediately after the code is verified correctly. The default validity period is 24 hours.
Request method and URL
1 2
POST http://api.gizwits.com/app/sms_code
Request paramters
Params
Data Type
Required
Param Type
Description
X-Gizwits-Application-Id
string
Yes
header
appid
X-Gizwits-Application-Token
string
Yes
header
App token, obtained by request an access token API
phone
string
Yes
body
Phone number
code
string
Yes
body
Verification code
Response Parameters
No
Get an image verification code
Debug console
The returned captcha_url is the URL of the image captcha and the image is displayed to the user.
Request method and URL
1 2
GET http://api.gizwits.com/app/verify/codes
Request paramters
Params
Data Type
Required
Param Type
Description
X-Gizwits-Application-Id
string
Yes
header
appid
X-Gizwits-Application-Token
string
Yes
header
App token, obtained by request an access token API
PUT https://api.gizwits.com/app/messages/{id}?status=1
Request paramters
Params
Data Type
Required
Param Type
Description
X-Gizwits-Application-Id
string
Yes
header
appid
X-Gizwits-User-token
string
Yes
header
User token
id
integer
Yes
path
Message ID
status
integer
Yes
query
Message status, 1 read, 2 delete
Response Parameters
No
Binding Management
After a device is bound to a user, there is a corresponding “binding role” relationship between the device and the user.
Binding roles are divided into four types, first bind users: special; owner user: owner; guest user: guest; normal user: normal
Role scenarioes description:
When the device is not shared and the device is not bound by any user. An A user is bound to the device. The A user becomes a special user. When a B user is bound to the device. The user B becomes a normal user.
Let the A user be a special user and the B user be a normal user. When the A user releases the binding and the B user becomes a special user, there is no “binding role” relationship between the A user and the device.
Let the A user be a special user and the B user be a normal user. The product turns on device sharing. The A user shares the device with the C user. Whether or not the C user accepts it, the A user becomes the owner user, and the B user becomes the guest user.
When sharing is turned on and the device does not have any user bindings. An A user is bound to the device. The A user becomes owner user and other users cannot bind the device.
Assume the A user as owner and C user has not bound the device. The A user shares the device with the C user, and the C user accepts the sharing. A user is still the owner and C is the guest.
Assume the A user as owner and B user as guest. The A user unbinds the device. There is no “binding role” relationship between A or B users and the device.
Other users cannot share the device except the owner user, there is only one owner for each device.
Binding device
You can bind the device in two ways:
Bind the device with product_key and MAC address
Bind the device with a QRCode. The content of QRCode is encrypted product_key and MAC, so it is essentially the same as the above one.
Bind a device by its MAC address
Debug console
Bind the user to the device.
Request method and URL
1 2
POST http://api.gizwits.com/app/bind_mac
Request paramters
Params
Data Type
Required
Param Type
Description
X-Gizwits-Application-Id
string
Yes
header
appid
X-Gizwits-User-token
string
Yes
header
User token
X-Gizwits-Timestamp
string
Yes
header
Request timestamp, The difference with the server time cannot exceed 5 minutes
X-Gizwits-Signature
string
Yes
header
Signature, calculated as lower(md5(product_secret + X-Gizwits-Timestamp))
product_key
string
Yes
body
Product_key
mac
string
Yes
body
Device mac address
remark
string
No
body
Remark
dev_alias
string
No
body
Device alias
set_owner
integer
No
body
Whether it is set to owner, it is only valid for products with device sharing enabled; 0 (default): not set as owner, 1: set as owner
Response Parameters
Params
Data Type
Description
product_key
string
Product_key
did
string
Device ID
mac
string
Device mac address
is_online
boolean
Whether online or not
passcode
string
Device passcode
host
string
Server domain name
port
integer
MQTT port number for M2M
port_s
integer
MQTT SSL port number for M2M
ws_port
integer
Websocket port number
wss_port
integer
Websocket SSL port number
remark
string
Device remark
is_disabled
boolean
Whether to log out or not
type
string
Device type, Single Item Device: normal, Central Control Device: center_control, Central Control Sub Device: sub_dev
dev_alias
string
Device alias
dev_label
Array[string]
List of device tags, currently used for devices control via voice API
role
string
Binding role, Special user: special, Owner user: owner, Guest user: guest, Normal user: normal
Only the QR code generated by Gizwits QR code generation service can be used to invoke this API (Here is the tutorial).
Request method and URL
1 2
POST https://api.gizwits.com/app/bind_latest
Request paramters
Params
Data Type
Required
Param Type
Description
X-Gizwits-Application-Id
string
Yes
header
appid
X-Gizwits-User-token
string
Yes
header
User token
qr_content
string
Yes
body
The string obtained by scanning the QR code
set_owner
integer
No
body
Whether to set as owner, only valid for products with device sharing enabled; 0 (default): not to set as owner, 1: set as owner
Response Parameters
No
Update binding information
Debug console
Users can modify aliases and notes of the bound devices. The same device can be bound by multiple users. Each user can set aliases and notes for the device without conflict.
Request method and URL
1 2
PUT https://api.gizwits.com/app/bindings/{did}
Request paramters
Params
Data Type
Required
Param Type
Description
X-Gizwits-Application-Id
string
Yes
header
appid
X-Gizwits-User-token
string
Yes
header
User token
did
integer
Yes
path
Device ID
remark
string
No
body
Device remark
dev_alias
string
No
body
Device alias
dev_label
Array[string]
No
body
List of device tags, currently used for devices control via voice API
Note: Fill in at least one of the body parameters.
Response Parameters
Params
Data Type
Description
remark
string
Device remark
dev_label
Array[string]
List of device tags, currently used for devices control via voice API
Get communication log and online&offline status records of a device
Debug console
Used to query the device’s communication log and online and offline status records for any two days in the last 7 days.
Input type (type)
Communication log query, type field value is cmd
Online and offline status records query, the type field value is online
Output type (type)
meta:
Communication log query, type field value is cmd
Online and offline status records query, the type field value is online
objects:
The type field value of the data returned by the communication log query: app2dev (app-to-device communication), dev2app (device-to-app communication)
The type field value of the data returned by the online and offline query: dev_online (online), dev_re_online (re-login before the offline process is completed), and dev_offline (offline)
The end timestamp end_time
Must be less than or equal to the current system timestamp
Must be greater than the start timestamp.
The difference between the end timestamp and the start timestamp must be less than 48 hours
Request method and URL
1 2
GET https://api.gizwits.com/app/devices/{did}/raw_data?type={type}&start_time={start_time}&end_time={end_time}
Request paramters
Params
Data Type
Required
Param Type
Description
X-Gizwits-Application-Id
string
Yes
header
appid
X-Gizwits-User-token
string
Yes
header
User token
did
string
Yes
path
DeviceID
type
string
Yes
query
cmd: communication log；online：online and offline record
start_time
integer
Yes
query
Start timestamp, in seconds
end_time
integer
Yes
query
End timestamp, in seconds
skip
integer
No
query
Number of skipped items, number of skip items + number of returned items must be <= 5000, default is 0
limit query
integer
No
query
The number of returned items, should be <=1000, the default is 20
sort
string
No
query
Sorting type, dese: descending order; ase: ascending order. The default is descending order
The type of the meta. Query type, cmd: communication log; online: online and offline record
type
string
The type of the objects. Type: app2dev: app-to-device communication; dev2app: device-to-app communication; dev_online: online; dev_re_online: login again before completing the offline process; dev_offline: offline
ip
string
IP address of the data reporter
payload_bin
string
Payload
timestamp
integer
Time for reporting data
source
string
This field is only available for app2dev type. The trigger type, d3: D3 trigger by rules engine; client: reporting data by clients
uid
string
This field is only available for app2dev type. User ID
appid
string
This field is only available for app2dev type. APP ID
The default format is a decimal array. The binary_coding parameter can be set as hex and base64.
If you want to send a payload of binary 011000010110001001100011, after every byte of the binary string is converted to a decimal, you will get an array: [97,98,99];
If you want to send a payload of hexadecimal 616263, after every byte of the binary string is converted to a decimal, you will get an array: [97,98,99].
1 2 3
{ "raw": [97,98,99] }
Data point (attrs):
Device products must have defined data points. If you want to set the value of the extended field binary to hexadecimal 1234567, you need to pad the extended field to the given length.
The default type of the extended field is hex16, and base64 can be used to set the binary_coding parameter as well.
1 2 3 4 5
{ "attrs": { "binary": "1234567000" } }
Request method and URL
1 2
POST https://api.gizwits.com/app/control/{did}
Request paramters
Params
Data Type
Required
Param Type
Description
X-Gizwits-Application-Id
string
Yes
header
appid
X-Gizwits-User-token
string
Yes
header
User token
did
string
Yes
path
Device ID
raw
Array[integer]
No
body
Raw instructions
attrs
object
No
body
Note: Fill in at least one of the body parameters
Response Parameters
No
Device Sharing
After the device sharing function is enabled, there are two binding roles: Owner and Guest.
There are two main ways to share devices:
Normal device sharing
Sharing devices via QR code
Sharing scenarios
Normal device sharing
The Owner selects a device to share, and invokes the create a sharing invitation API to create a sharing invitation
Both the Owner and Guest receive a device sharing message
The receiver invokes the query sharing invitation API to query the received invitation
The receiver call accept the sharing invitation API to accept the invitation and the receiver becomes Guest
Both the Owner and Guest receive a message after the device sharing invitation is accepted
Sharing devices via QR code
The Owner selects a device to share, and invokes the create a sharing invitation API to create a sharing invitation
The qr_content in the response has the QR code information, and the Owner displays the QR code image to the receiver
The receiver scans the QR code, obtains the invitation code, calls the get sharing invitation information of a given QR code API, and views the shared content.
Call the accept a sharing invitation by a given QRCode API, accept the sharing invitation, and the receiver becomes Guest
Both the Owner and Guest receive a device sharing message
Cancel device sharing
Owner invokes the cancel/retract a sharing invitation API, cancels invitation sent out, and recalls accepted invitation
If the Guest user has not accepted it, the Owner will receive a cancelation message of device sharing
The guest user’s binding to the device is cancelled. At the same time, both the Owner and Guest receive a cancelation message of device sharing.
Ownership transfer
The Owner invokes the transfer ownership of a device to a guest API and fills in the information of the device to be transferred and ID of the user to be the owner
The original Owner user unbinds the device. The original Guest user becomes the new Owner.
Create a sharing invitation
Debug console
This API can only be called by master account of the device.
If the type is normal sharing, use one field of uid/username/email/phone, which is the receiver information;
If the type is QR code sharing, the uid, username, email, and phone are set with empty values, if the setting does not take effect;
Normal sharing is expired for 24 hours, and the QR code sharing is expired for 15 minutes.
For QR code sharing, the client generates the QR code image locally after receiving the returned QR code content.
Request method and URL
1 2
POST https://api.gizwits.com/app/sharing
Request paramters
Params
Data Type
Required
Param Type
Description
X-Gizwits-Application-Id
string
Yes
header
appid
X-Gizwits-User-token
string
Yes
header
User token
type
integer
Yes
body
Sharing type, 0: Normal sharing, 1: QR code sharing
did
string
No
body
Device ID
uid
string
No
body
Normal sharing type, receiver user ID
username
string
No
body
Normal sharing type, receiver username
email
string
No
body
Normal sharing type, receiver email address
phone
string
No
body
Normal sharing type, receiver mobile number
duration
integer
No
body
Sharing duration, the length of time the device can be used after the guest accepts sharing. Unit: minutes. The minimum is 1 minute, the maximum is 1440 minutes
Response Parameters
Params
Data Type
Description
id
string
Sharing record ID for normal sharing
qr_content
integer
QR code image content, only for the QR code sharing
POST https://api.gizwits.com/app/sharing/code/{code}
Request paramters
Params
Data Type
Required
Param Type
Description
X-Gizwits-Application-Id
string
Yes
header
appid
X-Gizwits-User-token
string
Yes
header
User token
code
integer
Yes
path
Shared QR code content
Response Parameters
No
Update a guest or owner alias of a given invitation
Debug console
Request method and URL
1 2
PUT https://api.gizwits.com/app/sharing/{id}/alias?user_alias={user_alias}
Request paramters
Params
Data Type
Required
Param Type
Description
X-Gizwits-Application-Id
string
Yes
header
appid
X-Gizwits-User-token
string
Yes
header
User token
id
integer
Yes
path
Sharing record ID
user_alias
string
Yes
query
Response Parameters
No
Transfer ownership of a device to a guest
Debug console
Request method and URL
1 2
POST https://api.gizwits.com/app/sharing/1/transfer?uid=1
Request paramters
Params
Data Type
Required
Param Type
Description
X-Gizwits-Application-Id
string
Yes
header
appid
X-Gizwits-User-token
string
Yes
header
User token
did
string
Yes
Device ID
uid
string
Yes
query
New owner User ID
Response Parameters
No
Device Grouping
Common scenarios of device grouping:
Classify multiple devices into a single physical space, such as a room or living room. It is easy to manage.
Firstly invoke the create a group API to create a group and enter the group name.
To add/delete devices in the group in batches after successful creation, invoke the add devices into a group API and the remove devices from a group API.
View all the devices under a group by calling the get devices information of a given group API.
Unified control of multiple devices of the same product, such as: switch on/off all lights in the hallway.
Firstly invoke the create a group API to create a group and enter the group name and product PK.
To add/delete devices in the group in batches after successful creation, invoke the add devices into a group API and the remove devices from a group API.
Batch control of devices by sending commands to the devices within a device group by invoking the control all devices in a given group API.
Get all user groups
Debug console
Request method and URL
1 2
GET https://api.gizwits.com/app/group
Request paramters
Params
Data Type
Required
Param Type
Description
X-Gizwits-Application-Id
string
Yes
header
appid
X-Gizwits-User-token
string
Yes
header
User token
Response Parameters
Params
Data Type
Description
created_at
string
Device group creation time (UTC time)
updated_at
string
Device group update time (UTC time)
product_key
string
Product product_key, the group with single product key will have a value
group_name
string
Device group name
verbose_name
string
Product name, the group with single product key will have a value
Control all devices in a group from cloud, the API can only control the devices in a group with single PK.
Raw instructions (raw):
The default format is a decimal array. The binary_coding parameter can be set as hex and base64. If you want to send a payload of binary 011000010110001001100011, after every byte of the binary string is converted to a decimal, you will get an array: [97,98,99]; If you want to send a payload of hexadecimal 616263, after every byte of the binary string is converted to a decimal, you will get an array: [97,98,99].
1 2 3
{ "raw": [97,98,99] }
Data point (attrs):
Device products must have defined data points. If you want to set the value of the extended field binary to hexadecimal 1234567, you need to pad the extended field to the given length: The default type of the extended field is hex16, and base64 can be used to set the binary_coding parameter as well.
You can create rules for devices linkage to automatically control the state change of one or more devices when the status of other devices is changed.
Devices with such a functionality need to be bound to the same user. Devices under different products need to be associated with each other at first. After a devices linkage rule is created, it can be modified or deleted at any time.
Click to see detail tutorial
Get datapoints of all products that can be used by rules
Debug console
You can query the data points of all products bound to the appid by this API.
Request method and URL
1 2
GET https://api.gizwits.com/app/rules/params?product_key={product_key}
Request paramters
Params
Data Type
Required
Param Type
Description
X-Gizwits-Application-Id
string
Yes
header
appid
X-Gizwits-User-token
string
Yes
header
User token
product_key
string
Yes
query
Multiple PK are separated by “,”. When the field is empty, all PKs bound to the appid are used by default. When the used PK is not bound to the appid, it is invalid.
Response Parameters
Params
Data Type
Description
display_name
string
Data point display name
enum
Array
Enumeration value
type
string
Data type, numeric: int; boolean: bool; enumeration: enum; extended: binary
When the trigger mode is online/offline/alert/fault/data, the device that generates the corresponding event is specified by this trigger mode. The specified device is designated as the master device.
event parameter
Indicates the trigger mode of the rule. The meanings of the optional values are as follows:
Online : Device goes online
Offline : Device goese offline
Alert : An alarm occurred on one alarm data point of the device
Fault : A fault occurred on one fault data point of the device
Data : Device reported status
event_attr parameter
When the trigger mode is alert/fault, this parameter specifies the data point at which this alarm/fault occurs and its occurrence/recovery
1 2 3 4
"event_attr": { "attr_name": "datapoint_alert", // the data point at which this alarm/fault occurs "value": "1" // Occurrence/cancellation of alarm/fault, 1 means occurrence, 0 means cancellation }
Notes:
The “occurrence” of the alarm/fault mentioned here means that the value of the alarm/fault data point was reported as 0 last time, and is reported as 1 this time, then the alarm/failure occurs.
The “recovery” of the alarm/fault mentioned here means that the value of the alarm/fault data point was reported as 1 last time, and is reported as 0 this time, then the alarm/failure recovers.
Other situations are not of “occurrence” and “recovery”
input parameter
Specifies the device data to be used in the rule. Each object in the array represents data of one device. Ignore this parameter when you do not need to use the device data:
1 2 3 4 5
[{ "product_key": "pk1", // Product key of the device "did": "did1", // Device did "prefix": "device1" // The prefix used to reference the data point value of the device in the condition and output. If this parameter is set to device1, then device1.datapoint1 indicates referring to the data point datapoint1 of the device device1 }]
condition parameter
Specify the conditions to be satisfied by the trigger rule. The conditions in the array will be checked on a group-by-group basis in the cloud processing. When any group of conditions is met, the output action is triggered.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
[ [{ "left": "device1.datapoint1",// Left operand of comparison, the type of the operand needs to be the same as the type of the right operand "opt": "==", // Comparison operators, optional values are: >, >=, <, <=, ==, != (Note: Only numeric values can be compared) "right": "1" // Right operand of comparison, the type of the operand needs to be the same as the type of the left operand. When using a constant, note that "1" represents the number 1, and "'1'" or "\"1\"" is the string "1" }], [{//Each array represents a group of conditions. When all the conditions in the group are met, the group is met "left": "device1.datapoint1", "opt": "==", "right": "1" },{ "left": "device2.datapoint2", "opt": ">", "right": "25" }] ]
output paramter
Specify what needs to be done when the conditions are met. All groups of actions are performed in the cloud at the same time. Each group does not affect each other.
Raw instructions (raw):
The default format is a decimal array. If you want to send a payload of binary 011000010110001001100011, after every byte of the binary string is converted to a decimal, you will get an array: [97,98,99];
If you want to send a payload of hexadecimal 616263, after every byte of the binary string is converted to a decimal, you will get an array: [97, 98, 99].
1 2 3
{ "raw": [97,98,99] }
Data point (attrs):
Device products must have defined data points. If you want to set the value of the extended field binary to hexadecimal 1234567, you need to pad the extended field to the given length:
[ [{ // Each array represents a set of output actions, which are executed sequentially. When the previous action fails to execute, the following actions will not be executed "type": "devctrl", // output type, devctrl indicates to control device "did": "did1", // device did to be controlled "attrs": { // key-value format "datapoint1": 1, // set datapoint1 value as 1 "datapoint2": 25, "datapoint3": "黄色" } },{ "type": "delay", // output type, delay "delay": 5 // Delay time, unit: second },{ "type": "devctrl", "did": "QxP6E9qFwwzsqKb2UYf4uw", "raw": [1, 2, 3] // raw format }], [{ "type": "devctrl", "did": "QxP6E9qFwwzsqKb2UYf4uw", "attrs": { "datapoint1": 1, "datapoint2": 25, "datapoint3": "黄色" } }] ]
Request method and URL
1 2
POST https://api.gizwits.com/app/rules
Request paramters
Params
Data Type
Required
Param Type
Description
X-Gizwits-Application-Id
string
Yes
header
appid
X-Gizwits-User-token
string
Yes
header
User token
remark
string
No
body
Rule remarks
name
string
Yes
body
Rule name
did
string
Yes
body
Device ID
interval
integer
No
body
Minimum trigger interval (unit: seconds)
product_key
string
Yes
body
Product PK
event
string
Yes
body
Trigger mode
event_attr
object
No
body
When the trigger mode is alert/fault, [RulesEventAttr]
input
Array
Yes
body
Required device data in rules [RulesInput]
condition
Array
Yes
body
Rule condition[RulesCondition]
output
Array
Yes
body
Rule action [RulesOutput]
RulesEventAttr
——————
No
body
——————
attr_name
string
No
body
The data point at which this alarm/fault occurred
value
string
No
body
Occurrence/cancellation of alarm/fault, 1 means occurrence, 0 means cancellation
RulesOutput
——————
Yes
body
——————
did
string
Yes
body
Controlled device ID
type
string
Yes
body
Trigger type, devctrl: control device; delay: delay
attrs
object
No
body
Control device using data point mode
raw
Array
No
body
Raw instructions
delay
integer
No
body
Delay time, unit: second
RulesInput
——————
Yes
body
——————
did
string
Yes
body
The source device ID in the rule
prefix
string
Yes
body
The prefix used to reference the data point value of this device in the condition and output
product_key
string
Yes
body
The corresponding product PK of the source device in the rule
RulesCondition
——————
Yes
body
——————
opt
string
Yes
body
Comparison operators, optional values are: >, >=, <, <=, ==, != (Note: Only numeric values can be compared)
When the trigger mode is alert/fault, [RulesEventAttr]
input
Array
Yes
body
Required device data in rules [RulesInput]
condition
Array
Yes
body
Rules condition [RulesCondition]
output
Array
Yes
body
Rules action [RulesOutput]
RulesEventAttr
——————
No
body
——————
attr_name
string
No
body
The data point at which an alarm/fault occurred
value
string
No
body
Occurrence/cancellation of alarm/fault, 1 means occurrence, 0 means cancellation
RulesOutput
——————
Yes
body
——————
did
string
Yes
body
Controlled device ID
type
string
Yes
body
Trigger type, devctrl: control device; delay: delay
attrs
object
No
body
Control device using data point mode
raw
Array
No
body
Raw instructions
delay
integer
No
body
Delay time, unit: second
RulesInput
——————
Yes
body
——————
did
string
Yes
body
The source device ID in the rule
prefix
string
Yes
body
The prefix used to reference the data point value of this device in the condition and output
product_key
string
Yes
body
The corresponding product PK of the source device in the rule
RulesCondition
——————
Yes
body
——————
opt
string
Yes
body
Comparison operators, optional values are: >, >=, <, <=, ==, != (Note: Only numeric values can be compared)
right
string
Yes
body
Right operand of comparison
left
string
Yes
body
Left operand of comparison
Response Parameters
Params
Data Type
Description
rule_id
integer
Rule ID
Example Response
1 2 3
{ "rule_id": 1234 }
User Scenario
Get all scenarios
Debug console
Request method and URL
1 2
GET https://api.gizwits.com/app/scene
Request paramters
Params
Data Type
Required
Param Type
Description
X-Gizwits-Application-Id
string
Yes
header
appid
X-Gizwits-User-token
string
Yes
header
User token
Response Parameters
Params
Data Type
Description
id
string
Scenario ID
scene_name
string
Scenario name
created_at
string
Scenario creation time (UTC time)
updated_at
string
Scenario update time (UTC time)
remark
string
Scenario remarks
task_type
string
Scenario task type: “delay”: Delayed task, “device”: Control a single device task, “group”: Control the device group task (only control the group with a single product_key)
did
string
Device did, for a single control task
product_key
string
Product key, for the non-delayed task
group_name
string
Device group name, for the device group task
raw
string
For non-delayed task, raw instructions, base64 encoding
attrs
object
For non-delayed task, data point control commands, fill in order number for enumeration data point, fill in base64 encoded string for extended data point
dev_remark
string
Device remarks, for device control task
time
integer
Delay time for delayed task in seconds, maximum: 3600 seconds
The default format is base64. The binary_coding parameter can be set as hex. If you want to send a payload of 010203, after encoding you will get: AQID;
1 2 3
{ "raw": "AQID" }
Data point (attrs):
Device products must have defined data points. If you want to set the value of the extended field binary to hexadecimal 1234567, you need to pad the extended field to the given length: The default type of the extended field is hex16, and base64 can be used to set the binary_coding parameter as well.
Scenario task type: “delay”: Delayed task, “device”: Control a single device task, “group”: Control the device group task (only control the group with a single product_key)
time
integer
No
body
Delay time for delayed task in seconds, maximum: 3600 seconds
did
string
No
body
Device did, for a single control task
group_id
string
No
body
Device group ID for the device group task
attrs
object
No
body
For non-delayed task, data point control commands, fill in order number for enumeration data point, fill in base64 encoded string for extended data point
raw
string
No
body
For non-delayed task, raw instructions, base64 encoding
Response Parameters
Params
Data Type
Description
id
string
Scenario ID
Example Response
1 2 3
{ "id": "59c8d5c38c7d50001a21c872" }
Delete a scenario
Debug console
Request method and URL
1 2
DELETE https://api.gizwits.com/app/scene/{id}
Request paramters
Params
Data Type
Required
Param Type
Description
X-Gizwits-Application-Id
string
Yes
header
appid
X-Gizwits-User-token
string
Yes
header
User token
id
string
Yes
path
Scenario ID
Response Parameters
No
Update a scenario information
Debug console
Request method and URL
1 2
POST https://api.gizwits.com/app/scene/{id}
Request paramters
Params
Data Type
Required
Param Type
Description
X-Gizwits-Application-Id
string
Yes
header
appid
X-Gizwits-User-token
string
Yes
header
User token
id
string
Yes
path
Scenario ID
scene_name
string
Yes
body
Scenario name
remark
string
No
body
Scenario remarks
task_type
string
Yes
body
Scenario task type: “delay”: Delayed task, “device”: Control a single device task, “group”: Control the device group task (only control the group with a single product_key)
time
integer
No
body
Delay time for delayed task in seconds, maximum: 3600 seconds
did
string
No
body
Device did, for a single control task
group_id
string
No
body
Device group ID for the device group task
attrs
object
No
body
For non-delayed task, data point control commands, fill in order number for enumeration data point, fill in base64 encoded string for extended data point
raw
string
No
body
For non-delayed task, raw instructions, base64 encoding
Response Parameters
No
Get task execution status of a given scenario
Debug console
Request method and URL
1 2
GET https://api.gizwits.com/app/scene/{id}/task
Request paramters
Params
Data Type
Required
Param Type
Description
X-Gizwits-Application-Id
string
Yes
header
appid
X-Gizwits-User-token
string
Yes
header
User token
id
string
Yes
path
Scenario ID
Response Parameters
Params
Data Type
Description
status
integer
Scenario task execution status, 0: In progress; 1: Execution completed; 2: Execution failed; 3: Task not executed
Example Response
1 2 3
{ "status": 1 }
Perform a scenario task
Debug console
Request method and URL
1 2
POST https://api.gizwits.com/app/scene/{id}/task
Request paramters
Params
Data Type
Required
Param Type
Description
X-Gizwits-Application-Id
string
Yes
header
appid
X-Gizwits-User-token
string
Yes
header
User token
id
string
Yes
path
Scenario ID
Response Parameters
No
If return successfully, start to perform scenario task
Task Scheduling Management
Scheduled tasks are divided into the following categories:
One-time tasks
Weekly scheduled recurring tasks
Daily scheduled recurring tasks
The enabled status of each scheduled task can be set. Only those scheduled tasks that are enabled can be executed.
All APIs under scheduling task management use UTC time
Scheduling task management API can only set scheduled tasks for a single device
Get a list of scheduled tasks
Debug console
Request method and URL
1 2
GET https://api.gizwits.com/app/devices/{did}/scheduler?limit=20&skip=0
Request paramters
Params
Data Type
Required
Param Type
Description
X-Gizwits-Application-Id
string
Yes
header
appid
X-Gizwits-User-token
string
Yes
header
User token
did
string
Yes
path
Device ID for the scheduled task
limit
integer
No
query
The number of returned items
skip
integer
No
query
Indicates the number of skipped items, indirectly indicating the number of pages.
Response Parameters
Params
Data Type
Description
id
string
Task ID
created_at
string
Task creation time(UTC time)
product_key
string
Product PK
did
string
Device ID of the scheduled task
raw
string
Raw instructions
attrs
object
date
string
Execution time for one-time task
time
string
Scheduled task execution time, accurate to minute, format xx:xx, eg: 02:30
date and time must be filled in, and note that date and time are UTC time when performing scheduled tasks
Create weekly occurring scheduled tasks
repeat is a repeating days of each week, separated by multiple commas; For example, if a task is executed every Monday, it is set to “mon”, if executed every Monday and Wednesday, it is set to “mon, wed”;
When repeat is a repeating days of each week, the optional values are: mon,tue,wed,thu,fri,sat,sun
time must be filled in, and note that the week and time for performing scheduled tasks are UTC time
start_date and end_date can be filled in optionally, which indicate the date range for scheduled tasks to perform
Create daily occurring scheduled tasks
repeat is set with day
days is set with the date list for the task excution; For example, if the task is executed on the 1st of each month, set to [“1”]; if executed on the 1st, 15th of each month, set to [“1”, “15”]
time must be filled in, and note that days and time are UTC time when performing scheduled tasks
start_date and end_date can be filled in optionally, which indicate the date range for scheduled tasks to perform
Raw instructions (raw):
The default format is hex16. The binary_coding parameter can be set as base64. If you want to send a payload of binary 011000010110001001100011, after every byte of the binary string is converted to a hexadecimal, you will get: 616263;
1 2 3
{ "raw": 616263 }
Data point (attrs):
Device products must have defined data points. If you want to set the value of the extended field binary to hexadecimal 1234567, you need to pad the extended field to the given length: The default type of the extended field is hex16, and base64 can be used to set the binary_coding parameter as well.
The common task scheduling is a set of upgraded APIs for task scheduling management. It can create scheduled tasks for scenarios, groups, and individual devices.
Get a common scheduled task
Debug console
Request method and URL
1 2
GET https://api.gizwits.com/app/common_scheduler?did={did}&group_id={group_id}&scene_id={scene_id}&limit={limit}&skip={skip}
Request paramters
Params
Data Type
Required
Param Type
Description
X-Gizwits-Application-Id
string
Yes
header
appid
X-Gizwits-User-token
string
Yes
header
User token
did
string
No
path
Device ID for setting a scheduled task
group_id
string
No
path
Group ID
scene_id
string
No
path
Scenario ID
limit
integer
No
query
The number of returned items
skip
integer
No
query
Indicates the number of skipped items, indirectly indicating the number of pages.
Response Parameters
Params
Data Type
Description
id
string
Task ID
created_at
string
Task creation time(UTC time)
product_key
string
Product PK
scene_id
string
group_id
string
did
string
Device ID for setting a scheduled task
raw
string
Raw instructions
attrs
object
date
string
Execution time for one-time task
time
string
Scheduled task execution time, accurate to minute, format xx:xx, eg: 02:30
Only one of the did, group_id, and scene_id parameters need to be filled in. They are used to create scheduled tasks for device, devices group, and user scenario.
If more than one are filled in at the same time, the first valid string is taken according to the priority;
For scenario tasks, you do not need to fill in the raw and attrs commands. The filled value will be ignored.
Creating recurring tasks is same as the task scheduling management API.
Raw instructions (raw):
The default format is hex16. The binary_coding parameter can be set as base64. If you want to send a payload of binary 011000010110001001100011, after every byte of the binary string is converted to a hexadecimal, you will get: 616263;
1 2 3
{ "raw": 616263 }
Data point (attrs):
Device products must have defined data points. If you want to set the value of the extended field binary to hexadecimal 1234567, you need to pad the extended field to the given length: The default type of the extended field is hex16, and base64 can be used to set the binary_coding parameter as well.
The API can aggregate the numeric values of the data point reported by the device, and can aggregate the data point values into sum/average/maximum/minimum by hours/days/weeks/months.
You can get aggregated data for multiple data points at a time.
To use this API, you must request to open it at first. After its acception, data reported will be aggregated.
Debug console
Request method and URL
1 2
PUT https://api.gizwits.com/app/devdata/{did}/agg_data
Request paramters
Params
Data Type
Required
Param Type
Description
X-Gizwits-Application-Id
string
Yes
header
appid
X-Gizwits-User-token
string
Yes
header
User token
did
string
Yes
path
Device ID
start_ts
integer
Yes
query
Start time in milliseconds
end_ts
integer
No
query
End time in milliseconds
attrs
string
Yes
query
Numeric data point name, multiple data points separated by commas
[ { "status": 404, "error_message": "scene not found!", "error_code": 9220 }, { "status": 400, "error_message": "the scene does not belong to you!", "error_code": 9221 } ]
Detailed error information can be viewed in the following table Open API error code table.
Appendix: Open API error codes table
Error Code
Error Type
Description
9001
GIZ_OPENAPI_MAC_ALREADY_REGISTERED
mac already registered!
9002
GIZ_OPENAPI_PRODUCT_KEY_INVALID
product_key invalid
9003
GIZ_OPENAPI_APPID_INVALID
appid invalid
9004
GIZ_OPENAPI_TOKEN_INVALID
token invalid
9005
GIZ_OPENAPI_USER_NOT_EXIST
user not exist
9006
GIZ_OPENAPI_TOKEN_EXPIRED
token expired
9007
GIZ_OPENAPI_M2M_ID_INVALID
m2m_id invalid
9008
GIZ_OPENAPI_SERVER_ERROR
server error
9009
GIZ_OPENAPI_CODE_EXPIRED
code expired
9010
GIZ_OPENAPI_CODE_INVALID
code invalid
9011
GIZ_OPENAPI_SANDBOX_SCALE_QUOTA_EXHAUSTED
sandbox scale quota exhausted!
9012
GIZ_OPENAPI_PRODUCTION_SCALE_QUOTA_EXHAUSTED
production scale quota exhausted!
9013
GIZ_OPENAPI_PRODUCT_HAS_NO_REQUEST_SCALE
product has no request scale!
9014
GIZ_OPENAPI_DEVICE_NOT_FOUND
device not found!
9015
GIZ_OPENAPI_FORM_INVALID
form invalid!
9016
GIZ_OPENAPI_DID_PASSCODE_INVALID
did or passcode invalid!
9017
GIZ_OPENAPI_DEVICE_NOT_BOUND
device not bound!
9018
GIZ_OPENAPI_PHONE_UNAVALIABLE
phone unavailable!
9019
GIZ_OPENAPI_USERNAME_UNAVALIABLE
username unavailable!
9020
GIZ_OPENAPI_USERNAME_PASSWORD_ERROR
username or password error!
9021
GIZ_OPENAPI_SEND_COMMAND_FAILED
send command failed!
9022
GIZ_OPENAPI_EMAIL_UNAVALIABLE
email unavailable!
9023
GIZ_OPENAPI_DEVICE_DISABLED
device is disabled!
9024
GIZ_OPENAPI_FAILED_NOTIFY_M2M
fail to notify m2m!
9025
GIZ_OPENAPI_ATTR_INVALID
attr invalid!
9026
GIZ_OPENAPI_USER_INVALID
user invalid!
9027
GIZ_OPENAPI_FIRMWARE_NOT_FOUND
firmware not found!
9028
GIZ_OPENAPI_JD_PRODUCT_NOT_FOUND
JD product info not found!
9029
GIZ_OPENAPI_DATAPOINT_DATA_NOT_FOUND
datapoint data not found!
9030
GIZ_OPENAPI_SCHEDULER_NOT_FOUND
scheduler not found!
9031
GIZ_OPENAPI_QQ_OAUTH_KEY_INVALID
qq oauth key invalid!
9032
GIZ_OPENAPI_OTA_SERVICE_OK_BUT_IN_IDLE
ota upgrade service OK, but in idle or disable!
9033
GIZ_OPENAPI_BT_FIRMWARE_UNVERIFIED
bt firmware unverified,except verify device!
9034
GIZ_OPENAPI_BT_FIRMWARE_NOTHING_TO_UPGRADE
bt firmware is OK, but nothing to upgrade!
9035
GIZ_OPENAPI_SAVE_KAIROSDB_ERROR
Save kairosdb error!
9036
GIZ_OPENAPI_EVENT_NOT_DEFINED
event not defined!
9037
GIZ_OPENAPI_SEND_SMS_FAILED
send sms failed!
9038
GIZ_OPENAPI_APPLICATION_AUTH_INVALID
X-Gizwits-Application-Auth invalid!
9039
GIZ_OPENAPI_NOT_ALLOWED_CALL_API
Not allowed to call deprecated API!
9040
GIZ_OPENAPI_BAD_QRCODE_CONTENT
bad qrcode content!
9041
GIZ_OPENAPI_REQUEST_THROTTLED
request was throttled
9042
GIZ_OPENAPI_DEVICE_OFFLINE
device offline!
9043
GIZ_OPENAPI_TIMESTAMP_INVALID
X-Gizwits-Timestamp invalid!
9044
GIZ_OPENAPI_SIGNATURE_INVALID
X-Gizwits-Signature invalid!
9045
GIZ_OPENAPI_DEPRECATED_API
API deprecated!
9046
GIZ_OPENAPI_REGISTER_IS_BUSY
Register already in progress!
9077
GIZ_OPENAPI
email already exists but not activate!
9080
GIZ_OPENAPI_CANNOT_SHARE_TO_SELF
can not share device to self!
9081
GIZ_OPENAPI_ONLY_OWNER_CAN_SHARE
guest or normal user can not share device!
9082
GIZ_OPENAPI_NOT_FOUND_GUEST
guest user not found!
9083
GIZ_OPENAPI_GUEST_ALREADY_BOUND
guest user alread bound!
9084
GIZ_OPENAPI_NOT_FOUND_SHARING_INFO
sharing record not found!
9085
GIZ_OPENAPI_NOT_FOUND_THE_MESSAGE
message record not found!
9087
GIZ_OPENAPI_SHARING_IS_WAITING_FOR_ACCEPT
sharing alread created,waiting for the guest to accept!
Docs
