Part 3. Cloud API: APP Service APIs

DeviceMark Endpoints

Click an ▶ API endpoint to expand/collapse its content.
GET/device-marks/triggered/account/:account_id/device-group/:devicegroup_id/device-mode/:devicemode_id?create_date={create_date}&page={page}&pagesize={pagesize}&sort={-date,+device}
Purpose: Gets all triggered DeviceMark data according to account_id, devicegroup_id and devicemode_id.
Notes
The data will be filtered by DeviceMark_created date.
The search results can be sorted by different filed names in ascending or descending order, and also paged.
Request Method
GET
Changelog
Nov 11, 2017
Permission
Must verify that the app_id and app_key of the Header exists and in its correctness.
Request Parameters
Need Parameter Type Description
Required account_id String The account_id to be searched.
Required devicegroup_id String The devicegroup_id to be searched.
  • If the user searches all groups, the value will be 0.
Required devicemode_id String The devicemode_id to be searched.
  • If the DeviceMode is represented in all, the default value is 0.
Optional created_date String The time when the DeviceMark is created, by using timestamp (UTC).
  • The filter must follow the rule that the time at which the DeviceMark is created will be greater than today.
  • The default value = today.
Optional page String The page number to be searched.
  • The default value = 1.
Optional pagesize String The number of items in each page to be searched.
  • The default value = 10.
Optional sort String The value is ((+fieldname1,+fieldname2) or -fieldname)).
  • Symbol + = ascending order
  • Symbol - = descending order
  • This parameter supports for combination query.
  • The group order is from the left to right parameter.
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
devicemarks Array Get the list of the DeviceMark.
Return Values in the "devicemarks" array
Fields Type Description
devicemark_id String The ID number of DeviceMark.
devicemark_name String The name of DeviceMark.
devicemark_created_time Integer The sequence of DeviceMark.
devicemark_video_thumbnail_path String The thumbnail path of the Devicedata video of the DeviceMark.
devicemark_devicename String The device name in which the DeviceData is created of the DeviceMark.
devicemark_video_read Integer The read status of the DeviceData of the DeviceMark.
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752,
  "devicemarks": [{
    "devicemark_id": "c92be72d-40fc-462f-ae52-9e997e514277",
    "devicemark_name":"Baby is asleep",
    "scemark_created_time": 1500617357,
    "devicemark_video_thumbnail_path": "https://nice.cloud.com/devicedatavideo/gtuss",
    "devicemark_video_read": 1,
    "devicemark_devicename": "Ray’s Baby Room"
  }]
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_ACCOUNT_ID account_id does not exist.
400 INVALID_DEVICEGROUP_ID devicegroup_id does not exist.
400 INVALID_SCENEMODE_ID devicemode_id does not exist.

▲ Top

GET/device-marks/triggered/account/:account_id/device/:device_id?create_datetime={create_datetime}&page={page}&pagesize={pagesize}&sort={-date,+device}
Purpose: Gets all related DeviceMark data according to account_id and device_id.
Notes
The data will be filtered by devicemark_created_time.
The search results will be listed in pages and sorted.
Request Method
GET
Changelog
Nov 11, 2017
Permission
Must verify that the app_id and app_key of the Header exists and in its correctness.
Request Parameters
Need Parameter Type Description
Required account_id String The account_id to be searched.
Required device_id String The device_id to be searched.
Optional created_date String The time when the DeviceMark is created, by using timestamp (UTC).
  • The filter must follow the rule that the time at which the DeviceMark is created will be greater than today.
  • The default value = today.
Optional page String The page number to be searched.
  • The default value = 1.
Optional pagesize String The number of items in each page to be searched.
  • The default value = 10.
Optional sort String The value is ((+fieldname1,+fieldname2) or -fieldname)).
  • Symbol + = ascending order.
  • Symbol - = descending order.
  • This parameter supports for combination query.
  • The group order is from the left to right parameter.
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
devicemarks_history Array Get the list of the DeviceMark history.
Return Values in the "devicemarks" array
Fields Type Description
devicemark_id String The ID number of the DeviceMark.
devicemark_name String The name of the DeviceMark.
devicemark_created_time Integer The created time of the DeviceMark.
devicemark_video_id String The devicemark_video_id of the DeviceMark.
devicemark_video_url String The devicemark_video_url of the DeviceMark.
devicemark_video_duration String The devicemark_video_duration of the DeviceMark.
devicemark_video_thumbnail_path String The thumbnail path of DeviceData video of the DeviceMark.
devicemark_devicename String The device name in which the DeviceData is created of the DeviceMark.
devicemark_video_read Integer The read status of the DeviceData of the DeviceMark.
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752,
  "devicemarks_history": [{
    "devicemark_id": "c92be72d-40fc-462f-ae52-9e997e514277",
    "devicemark_name":"Baby is asleep",
    "devicemark_video_id": "sdeew090-40fc-462f-ae52-9e997e514277",
    "devicemark_video_duration": "sdeew090-40fc-462f-ae52-9e997e514277",
    "devicemark_video_url": "https://nice.cloud.com/devicedatavideo/dsagw",
    "devicemark_video_thumbnail_path": "https://nice.cloud.com/devicedatavideo/gtuss",
    "devicemark_video_read": 1,
    "devicemark_devicename": "Ray’s Baby Room",
    "devicemark_created_time": 1500617357
  }]
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_ACCOUNT_ID account_id does not exist.
400 INVALID_DEVICE_ID device_id does not exist.

▲ Top

GET/device-marks/triggered/account/:account_id/device/:device_id/latest
Purpose: Get the latest DeviceMark data according to account_id and device_id.
Notes
The results will be arranged in time sequence.
Request Method
GET
Changelog
Nov 11, 2017
Permission
Must verify that the app_id and app_key of the Header exists and is correct.
Request Parameters
Need Parameter Type Description
Required account_id String The account_id to be searched.
Required device_id String The device_id to be searched.
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
devicemarks_latest Object (Array) The latest results of the DeviceMark.
Return Values in the devicemarks_latest array
Fields Type Description
devicemark_id String The ID number of the DeviceMark.
devicemark_name String The name of the DeviceMark.
devicemark_created_time Integer The created time of the DeviceMark.
devicemark_video_thumbnail_path String The thumbnail path of the DeviceData video of the DeviceMark.
devicemark_devicename String The device name in which the DeviceData is created of the DeviceMark.
devicemark_video_read Integer The read status of the DeviceData of the DeviceMark.
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752,
  "devicemark_latest": [{
    "devicemark_id": "c92be72d-40fc-462f-ae52-9e997e514277",
    "devicemark_name":"Baby is asleep",
    "devicemark_video_thumbnail_path": "https://nice.cloud.com/devicedatavideo/gtuss",
    "devicemark_video_read": 1,
    "devicemark_devicename": "Ray's Baby Room",
    "scemark_created_time": 1500617357
  }]
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_ACCOUNT_ID account_id does not exist.
400 INVALID_DEVICE_ID device_id does not exist.

▲ Top

GET/device-marks/:devicemark_id/triggered/account/:account_id/detail
Purpose: Gets the details of the DeviceMark according to account_id and devicemark_id.
Request Method
GET
Changelog
Nov 11, 2017
Permission
Must verify that the app_id and app_key of the Header exists and are correct.
Request Parameters
Need Parameter Type Description
Required account_id String The account_id to be searched.
Required devicemark_id String The devicemark_id to be searched.
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
devicemarks_detail Object (Array) The searched details of the DeviceMark.
Return Values in the devicemarks_detail array
Fields Type Description
devicemark_id String The ID number of the DeviceMark.
devicemark_name String The name of the DeviceMark.
devicemark_created_time Integer The created time of the DeviceMark.
devicemark_video_id String The devicemark_video_id of the DeviceMark.
devicemark_video_url String The devicemark_video_url of the DeviceMark.
devicemark_video_thumbnail_path String The thumbnail path of DeviceData video of the DeviceMark.
devicemark_devicename String The device name in which DeviceData is created of the DeviceMark.
devicemark_device_groupname String The device group name in which DeviceData is created of the DeviceMark.
devicemark_video_read Integer The read status of the DeviceData of the DeviceMark.
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752,
  "devicemark_detail": [{
    "devicemark_id": "c92be72d-40fc-462f-ae52-9e997e514277",
    "devicemark_name": "Baby is asleep",
    "devicemark_video_id": "sdeew090-40fc-462f-ae52-9e997e514277",
    "devicemark_video_url": "https://nice.cloud.com/devicedatavideo/dsagw",
    "devicemark_video_thumbnail_path": "https://nice.cloud.com/devicedatavideo/gtuss",
    "devicemark_video_read": 1,
    "devicemark_devicename": "Ray's Baby Room",
    "devicemark_device_groupname": "Baby Room",
    "devicemark_created_time": 1500617357
  }]
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_ACCOUNT_ID account_id does not exist.
400 INVALID_SCENEMARK_ID devicemark_id does not exist.

▲ Top

DELETE/device-marks/triggered/account/:account_id/detail
Purpose: As the DeviceData from the triggered DeviceMark is deleted in the device, the DeviceData will be marked as "deleted" and pended to be deleted by the system, or until the main user deletes the DeviceData permanently.
Request Method
DELETE
Changelog
Nov 11, 2017
Permission
Must verify that the app_id and app_key of the Header belong to the App to take further actions.
Request Parameters
Need Parameter Type Description
Required devicemark_id String The devicemark_id to be deleted.
  • Support multiple items deletion by using semicolon to separate devicemark_id.
Required account_id String The account_id which the deleted DeviceMark belongs to.
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
devicemark_id String The deleted devicemark_id. Multiple devicemark_id can be separated by using commas.
account_id String The account_id which the deleted DeviceMark belongs to.
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752,
  "devicemark_id":"c92be72d-40fc-462f-ae52-9e997e514277,c92be72d-40fc-462f-ae52-9e997e514271,c92be72d-40fc-462f-ae52-9e997e514273",
  "account_id": "c92be72d-40fc-462f-ae52-9e997e514277"
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_ACCOUNT_ID account_id does not exist.
400 INVALID_SCENEMARK_ID devicemark_id does not exist.

▲ Top

PUT/device-marks/triggered/account/:account_id/read
Purpose: Flags the read status of the DeviceMark as "read".
Request Method
PUT
Changelog
Nov 11, 2017
Permission
Must verify that the app_id and app_key of Header exists and correct.
Request Parameters
Need Parameter Type Description
Required devicemark_id String The devicemark_id to be marked.
  • Multiple devicemark_id's can be separated by using commas.
Required account_id String The account_id which the flagged DeviceMark belongs to.
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
devicemark_id String The deleted devicemark_id.
  • Multiple devicemark_id's can be separated by using commas.
account_id String The account_id which the marked DeviceMark belongs to.
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752,
  "devicemark_id": "c92be72d-40fc-462f-ae52-9e997e514277,c92be72d-40fc-462f-ae52-9e997e514277,c92be72d-40fc-462f-ae52-9e997e514277,c92be72d-40fc-462f-ae52-9e997e514277",
  "account_id": "c92be72d-40fc-462f-ae52-9e997e514277"
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_ACCOUNT_ID account_id does not exist.
400 INVALID_SCENEMARK_ID devicemark_id does not exist.

▲ Top

GET/device-marks/account/:account_id/unread
Purpose: Gets all unread of DeviceMarks based on the created time of the DeviceMark.
Request Method
GET
Changelog
Nov 11, 2017 First version
Dec 21, 2017 Second version
Permission
Must verify that the app_id and app_key of Header belong to the App to take further actions.
Request Parameters
Need Parameter Type Description
Required account_id String The account_id which the unread DeviceMark belongs to.
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
devicemark_unread Object (Array) The detailed object of the unread DeviceMarks.
Return Values in the "devicemark_unread" array
Fields Type Description
devicemark_created_date String The date when DeviceMark is generated by using Timestamp (UTC).
unreadcount Integer The unread count of DeviceData.
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752,
  "devicemark_unread": [{
    "devicemark_created_date": 1,
    "unreadcount": 1
  }]
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_ACCOUNT_ID account_id does not exist.

▲ Top

PUT/device-marks/account/:account_id/signedurl
Purpose: Sign and re-sign the DeviceMark URL to see if the user is able to read the DeviceMark (Invalid DeviceMark URL cannot be read, or unauthorized user cannot read the DeviceMark).
Request Method
PUT
Changelog
Nov 11, 2017
Permission
Must verify that the app_id and app_key of the Header belongs to the App to take further actions.
Request Parameters
Need Parameter Type Description
Required account_id String The account_id which the unread DeviceMark belongs to.
Required devicemark_id String The DeviceMark URL to be signed.
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
account_id String The account_id which the marked DeviceMark belongs to.
signed_devicemark_url String The signed DeviceMark URL.
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752,
  "signed_devicemark_url": "http://werqwerqew.qwerqwer.aws.com?sign=323adsfadfq341324",
  "account_id ": "c92be72d-40fc-462f-ae52-9e997e514277"
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_ACCOUNT_ID account_id does not exist.
400 INVALID_SCENEMARK_ID devicemark_url does not exist.

▲ Top

DELETE/device-marks/triggered/account/:account_id/temporary/
Purpose: Permanently deletes a DeviceMark.
Request Method
DELETE
Changelog
Nov 11, 2017
Permission
Must verify that the app_id and app_key of the Header belongs to the App to take further actions.
Request Parameters
Need Parameter Type Description
Required datalandmark_id String The ID number of the datalandmark.
  • Multiple datalandmark_id's can be separated by using commas.
Required account_id String The unique identification of each account.
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
datalandmark_id String The ID number of the datalandmark.
account_id String The unique identification of each account.
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752,
  "datalandmark_id": "c92be72d-40fc-462f-ae52-9e997e514277"
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_DATALANDMARK_ID datalandmark_id does not exist.

▲ Top

PUT/device-marks/triggered/account/:account_id/temporary/
Purpose: Recovers a deleted DeviceMark.
Request Method
PUT
Changelog
Nov 11, 2017
Permission
Must verify that the app_id and app_key of the Header belongs to the App to take further actions.
Request Parameters
Need Parameter Type Description
Required datalandmark_id String The ID number of the datalandmark.
  • Multiple datalandmark_id's can be separated by using commas.
Required account_id String The unique identification of each account.
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
datalandmark_id String The ID number of the datalandmark.
account_id String The unique identification of each account.
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752,
  "datalandmark_id": "c92be72d-40fc-462f-ae52-9e997e514277"
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_DATALANDMARK_ID datalandmark_id does not exist.

▲ Top