Part 3. Cloud API

API Definition

On this page...

APP access with OAuth

APPs access a device and account service by using OAuth. Each API defines the following items:

  • Name
    • It goes after /XXX. XXX represents the feature category. For example: /Accounts/Registration.
    • It means the API is provided by Account.
    • Registration means this API will create a unique account and main user.
  • URL path
    • Example application, service portal and end user apps must be accessed via the URL to retrieve every API. For example, the path goes: /api hostname/api version/api url.
  • Method
    • Each method in its own API has to be defined when you use the API. For example: /Accounts/Registration API.
    • Call the method, and POST creates a unique account and main user.
    • Note: The parameter name will be italicized in each API introduction.
How to start using Example Cloud APIs
Applying a unique APP ID and Key

Before starting to use Cloud API, developers need to apply a unique APP ID and Key for the APP. A developer’s APP ID (app_id and app_key) is the certificate that the developer uses to access Example cloud APIs. When the developer changes the purchase options, payment method, or billing address, the developer's information will also be updated in which the developer uses the APP ID (app_id and app_key). See the following image and step-by-step description.

Step 1. Registration of a Example developer account.
The developer registers a user account at the Example service portal or APP.
Step 2. Tap the developer’s information.
The developer fills in contact information. For example: phone number, email address, etc.
Step 3. Create an app_id and app_key.
The developer’s basic information is required as follows:
  • The developer selects the type of app_id and app_key: Purchased or trial version
  • The developer selects app_id and app_key application platform: Android, iOS, Windows, HTML5.
  • The developer enters the name and description of the APP.
  • Example service generates app_id and app_key.
Step 4. The developer checks the account information.
The developer may check the account information at Example Service Portal, including payment conditions, app_id and app_key.

▲ Top

Overall API Lists
Cloud API Endpoint lists

The following tabular data tables provide lists of Cloud API Endpoints with a description of each available service. These services provide RESTful interfaces, and Example is actively updating each API to follow the Cloud API Specification.

  • The details of the Notification API and CV/AI API endpoints are further explained in the Cloud API: Web Services section.
  • The details of the APP API Service endpoints are further explained in the Cloud API: APP Service API Endpoints section (except the API Endpoint list for API Service Management).

The APIs are currently classified into 10 types:

  1. Administrative Functions for Account and Permissions Management
  2. Archival Functions for DeviceData Write/Read/Purge/URI Management
  3. Streaming API - Middleware mediated media/meta-data streaming to end-users
  4. DeviceMode Functions
  5. Device & CaptureMode Functions - Middleware mediated device-user communication
  6. DeviceData Management Functions
  7. DeviceMark Management Functions for Generate/Revise/Purge/Query etc.
  8. Big Data & Meta Analysis Functions
  9. External Web Service (WS) Functions for asynchronous dispatch of AI, CV analytics
  10. External Web Service (WS) Functions for SNS and Notification

Lists of overall Cloud APIs are provided below. For further reference, click an API page link external link icon.

Notification API endpoints external link icon
External Web Service (WS) Functions for SNS and Notification
Method URI Description
GET /notifications Get the list of the notifications.
POST /notifications/:notification_type/devices/:device_id Once any connection error or changes happen, the system will send the notifications.
POST /notifications/:notification_type/:datalandmark_id Once datalandmark_id (DeviceMark) is created, the system will send the notifications.
GET /notifications/accounts/:account_id Get today’s unsent notifications according to account_id.

▲ Top

CV/AI API endpoints external link icon
External Web Service (WS) Functions for asynchronous dispatch of AI, CV analytics
Method URI Description
POST /face/detect Detect and analyze facial features (e.g., eyes, emotion, etc.). The results will return each type of analysis value of the target image.
Other API endpoints external link icon
Big Data & Meta Analysis Functions
Method URI Description
POST /actions Record user activity logs (for example, manual recording and photo-taking).
Application API endpoints external link icon
Administrative Functions for Account and Permissions Management
Method URI Description
POST /apps Add new App (Register App).
PUT /apps/:app_id Update App Data.

▲ Top

Account API endpoints external link icon
Administrative Functions for Account and Permissions Management
Method URI Description
POST /accounts/registration Registration: Create a unique account and main user.
PUT /accounts/:account_id Edit the account's information.
GET /accounts/:account_id Get the single account's information.
GET /accounts/app/:app_id Get the single account's information.
POST /accounts/verifycode Send the verification code when the user forgets the password or registers for a new account.
PUT /accounts/verifycode Verify the correctness of the verification code.
POST /accounts/status Activate / deactivate the account.
PUT /accounts/:account_id/reset-password User changes the password.
PUT /accounts/forgotpassword User forgets the password.
POST /accounts/login/local Local login (including account name and password). User account must be activated.
PUT /accounts/login/others Third-party app login (WeChat, Facebook…).
PUT /accounts/refresh-token Extend access token.
POST /accounts/authorize After you have received the code value, you can redeem this code for a set of tokens that allow you to authenticate with the API.
GET /accounts/logout?client_id={client_id}&redirect_uri={redirect_uri} Log out. Delete the token when the user logs out.
GET /accounts/:account_id/token/:account_token The API token only allows 90 seconds for the user to log in. Note: "90 seconds" is one of the suggested options. The time can be modified.
POST /accounts/password-strength Calculate the password strength. The password must have "Strong" strength.
Account flows

This section is to explain how the App is linked to the user's account and the user.

  1. The end user selects an app from a third-party App store or Example Service Provider App store.
  2. The downloaded App initiates "Link to My Example Account" or a third-party account (e.g., Facebook, WeChat) in the App. This creates a redirection to the Example Account Service.
  3. The account table will be linked to the user and device table.
  4. The App to access the device is associated with the user's account.

▲ Top

DeviceMode API endpoints external link icon
DeviceMode Functions
Method URI Description
GET /device-modes/account/:account_id Get DeviceMode by account_id

▲ Top

Retention API Endpoints external link icon
Administrative Functions for Account and Permissions Management
Method URI Description
GET /retentions Get the list of pricing plan.
POST /retentions/:retention_id/account/:account_id Confirm the pricing plan according to the account ID. (Submit purchasing selection, and generate the order ID number).
PUT /retentions/orders/:order_id/status/:order_status Callback API when the purchase is completed (including order status update, payment completed/failed ...).
GET /retentions/orders/account/:account_id Get the order list of the pricing plan according to the account ID.
GET /retentions/orders/:order_id Get the order details.

▲ Top

DeviceMark API Endpoints external link icon
DeviceMark Management Functions for Generate/Revise/Purge/Query ...
Method URI Description
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} Get all triggered DeviceMark data according to account_id, devgroup_id and devicemode_id. The data will be filtered by the DeviceMark_created date.
GET /device-marks/triggered/account/:account_id/device/:device_id?create_datetime={create_datetime}&page={page}&pagesize={pagesize}&sort={-date,+device} Get all related DeviceMark data according to account_id and device_id. The data will be filtered by the DeviceMark_created date.
GET /device-marks/triggered/account/:account_id/device/:device_id/latest Get all latest DeviceMarks data according to account_id and device_id.
GET /device-marks/:devicemark_id/triggered/account/:account_id/detail Get the details of the DeviceMark according to account_id and devicemark_id.
DELETE /device-marks/triggered/account/:account_id/detail Delete the DeviceMark temporary.
PUT /device-marks/triggered/account/:account_id/read Flag the read status of the DeviceMark as "read".
GET /device-marks/account/:account_id/unread Get all unread DeviceMarks based on the created date of the DeviceMark according to account_id.
PUT /device-marks/account/:account_id/signedurl Sign and re-sign the DeviceMark URL.
DELETE /device-marks/triggered/account/:account_id/temporary/ Permanently delete the DeviceMark.
PUT /devicemarks/triggered/account/:account_id/ temporary / Recover the deleted DeviceMark.
DeviceMark flows

A DeviceMark is created when CV/AI analytics find that the analysis on the DeviceData satisfies Device-opening conditions defined by the DeviceMode.

▲ Top

Device Group API Endpoints external link icon
Administrative Functions for Account and Permissions Management
Method URI Description
POST /device-groups/share/account/:account_id Main user adds view permissions of device group to users.
DELETE /device-groups/share/account/:account_id Main user removes the user’s view permissions of device group.
GET /device-groups/account/:account_id Get the list of device group by account (allow device group setting).
GET /device-groups/share/account/:account_id Get the list of device group by account (to view the shared device groups).
POST /device-groups/account/:account_id Add new device group to the account.
PUT /device-groups/:devgroup_id/account/:account_id Update device group information based on the devgroup_id and account_id.
DELETE /device-groups/:devgroup_id/account/:account_id Delete device group based on the devgroup_id and account_id.

▲ Top

Device API Endpoints external link icon
Administrative Functions for Account and Permissions Management
Method URI Description
POST /devices/:device_id/device-group/:devgroup_id Organize the device into device group
POST /devices/share/account/:account_id Main user adds view permissions of device to user.
DELETE /devices/share/account/:account_id Main user removes view permissions of device for user.
POST /devices Add the user's own device information.
GET /devices/device-group/:devgroup_id Get the list of devices by device group (including streaming URL).
GET /devices/:device_id Get device information based on the device_id.
PUT /devices/:device_id Update device information based on the device_id.
DELETE /devices/:device_id Delete device based on the device_id.
GET /devices/:device_id/attributes Get the camera capability, for example: resolutions, frame rate, sensor type ...
POST /devices/zone The API is invoked when the user marks the region of interest (ROI) while viewing the recorded videos or photos on the device.

▲ Top

Other API Endpoints external link icon
DeviceData Management Functions
Method URI Description
PUT /restore/:datalandmark_id Recover deleted items (for example, device, video, photos…).

▲ Top

The following APIs are only allowed for API Service Management.
Application
Method URI Description
PUT /apps/:app_id/status/:app_status Activate / deactivate App.
PUT /apps/:app_id/key Update App Key.
Account
Method URI Description
POST accounts/app/:app_id Add new account - Add to specific APP.
DeviceMode
Method URI Description
POST /device-modes Add DeviceMode.
PUT /device-modes/:devicemode_id Update DeviceMode.
DELETE /device-modes/:devicemode_id Delete DeviceMode.
DeviceMark
Method URI Description
POST /device-marks Add new DeviceMark.
DELETE /device-marks/:devicemark_id Delete DeviceMark.
Retention
Method URI Description
POST /retentions Add new storage capacity plan.
DELETE /retentions/:retention_id Delete storage capacity plan.
GET /retentions/orders Get all order lists of all plans.
Notification
PUT /notifications/:notification_id Update notifications
POST /notifications Add new notifications.
Delete /notifications/:notification_id Delete notifications.

▲ Top