A detailed documentation of all available APIs can be found in Device Management API Documentation. Here are some basic use-cases.
- List all cameras claimed to an Azena account
- Claim a device to an Azena account
- List all cameras claimed via API
- Get a list of all available applications/licenses in your account
- Get number of available applications/licenses for specific application
- Install application on online camera
- Install an application on offline camera
- Uninstalling applications from online camera
- Get all applications currently installed on online camera
- Starting and stoping an application
- Updating an application
- How to handle errors and retry failed requests
- How to handle batch requests
 |
Some API endpoints require additional permissions and will not work out of the box with your Azena credentials. If you would like to make full use of our API suite, please contact support to request this additional functionality. It is possible to add additional permissions to your personal user account or to create a dedicated technical user for your company. |
List all cameras claimed to an Azena account
Our Device Management API offers a possibility to list all cameras claimed to an Azena account. Please use the Device Management Tool or login to the camera web-frontend to claim a device to the Azena Cloud. A description on how to access camera web-frontend can be found in Connecting Cameras section.
Claim a device to an Azena account
Devices require an active internet connection in order to be claimed to the Azena Platform. More information on potential URL whitelisting can be found here. More information on how to claim a device can be found here.
List all cameras claimed via API
Returns a list of cameras claimed to the Azena account. Additional filters can be set in the query to limit the number of results.
Remarks:
- The maximum number of returned devices is currently limited to 1000. In case there are more devices claimed to your account, use the page query parameter until the API does not provide any devices anymore.
- Devices in state UNCLAIMED are devices that have installed licenses associated to your account, even if the devices themselves have not been claimed to your account before. This is used to keep track of your license usage also on offline devices.
- The returned deviceID is used to identify a device and is used to perform further API actions.
Get a list of all available applications/licenses in your account
API: GET /license/v1/licensequantities
Returns a list that contains the number of used and free license quantities per application and license type in your account. Application license quantities need to be bought via the Azena Application Store.
Get number of available applications/licenses for specific application
API: GET /license/v1/licensequantities/apps/{appId}
Returns the number of free and used quantities of licenses for a specific application ID and license type.
Install application on online camera
Step 1: Buy license type quantity for application ID
Application license quantities need to be bought via the Azena Application Store.
Step 2: Check quantities for application and license type
See Get a list of all available applications/licenses in your account section.
Step 3: Get device ID
See List all cameras claimed via API section.
Step 4: Install application on device
API: PUT /software/v1/apps/{appId}/devices/{deviceId}
Installs the application on the device with the license type specified in payload (FULL, TRIAL, SUBSCRIPTION). Prerequisite is an existing free license quantity for the given license type and application ID and an active internet connection of the device.
Install an application on offline camera
Step 1: Buy license type quantity for application ID
Application license quantities need to be bought via the Azena Application Store.
Step 2: Check quantities for application and license type
See Get a list of all available applications/licenses in your account section.
Step 3: Get device ID
For claimed devices: See List all cameras claimed via API section.
For offline devices: Use ONVIF Discovery.
Step 4: Check for existing license
Check whether a license for specific app and device combination already exists:
API: GET /license/v1/licenses/apps/{appId}/devices/{deviceId}
The response will be an array of license information, each including license ID, license token, application ID and license type.
Step 5: Generate new license (optional)
Generate a new license for a given application ID, device ID and license type. Remark: For license type SUBSCRIPTION, you also need to provide the order ID.
Returns license information for the license created, including a unique license token. Each license has a unique license ID and is bound to a device ID and application ID.
Step 6: Download License
API: GET /license/v1/licenses/{licenseId}/token
Triggers download of a license file with given license ID.
Step 7: Download Application
API: GET /software/v1/apps/{appId}/download
Triggers download of the application .apk binary file.
Step 8: Upload Application and License on Device via ONVIF
Upload the license file and the .apk file on your camera via ONVIF API, see ONVIF server.
Uninstalling applications from online camera
API: DELETE /software/v1/apps/{appId}/devices/{deviceId}
Will uninstall an application from a device. This will automatically return the license to your Azena account.
Get all applications currently installed on online camera
API: GET /device/v1/devices/{deviceId}/apps
Returns all application IDs currently installed on a device with specified device ID.
Starting and stoping an application
Get application status for a device
API: GET /software/v1/apps/{appId}/devices/{deviceId}
Returns information about application installation state, application running state and whether the app is updatable.
Start or stop application
API: POST /software/v1/apps/{appId}/devices/{deviceId}/state/RUNNING
Starts application on online device.
API: POST /software/v1/apps/{appId}/devices/{deviceId}/state/NOT_RUNNING
Stops application on online device.
Updating an application
Follow the optional steps to get information which devices need to be updated.
Step 1: Get all devices with available application updates
With filter option you can query all devices in your account that have applications installed that can be updated.
API: GET /device/v1/devices?appsUpdatePossible=true
Step 2: Get all applications currently installed on device
API: GET /device/v1/devices/{deviceId}/apps
Returns all application IDs and application status for applications currently installed on a device.
Step 3: Check what application is updatable (optional)
API: GET /software/v1/apps/{appId}/devices/{deviceId}
Returns app status including information whether the app is updatable (true or false).
Step 4: Update app
API: POST /software/v1/apps/{appId}/devices/{deviceId}
Triggers an update of the given application to the latest version.
Step 5: Check success
You can execute Step 3 or 1 again to verify if the update was successful. Since the update can take several minutes you should wait long enough before executing this step.
How to handle errors and retry failed requests
When you send requests to the Device Management API you might encounter certain errors sometimes. They can be categorized into client errors (4xx error codes) and server errors (5xx error codes).
Client errors usually indicate problems that need to be fixed by the client, like missing authentication or missing parameters.
Server errors usually indicate problems like server maintenance that need to be resolved by Azena. You can retry the request until it succeeds.
| error code | what does it mean |
| 400 | Bad request. Something is wrong with the request, e.g. a mandatory parameter is missing. |
| 401,403 | Access denied. Authorization is missing, wrong or expired. |
| 404 | Not found. The object could not be found or the url is wrong. |
| 408 | Timeout. There might be an issue with your network connection. Retry the request after a few seconds. |
| 429 | Too many requests. You are sending too many requests in a short period of time. Retry the request after a few seconds. |
| 500,502,503,504 | Server error. Retry the request after a few minutes. If the error persists contact support. |
How to handle batch requests
If you want to install applications on multiple devices or if you want to update multiple applications there are a few things to consider.
Devices will start to download applications which might be quite large. So in order to not overwhelm your own network you should consider only installing/updating a small number of applications at once or even one-by-one. You might also run into timeouts or rate limiting while executing these requests, so robust error handling and retry policy needs to be implemented.
regular batch installation:
batch installtion with error handling: