v1/firmware_updates

Use the v1/firmware_updates API to update the firmware of your devices and check their status.

URI

https://<hostname>/ws/v1/firmware_updates

Formats

HTTP method	Format	Description	Parameters
GET	/ws/v1/firmware_updates	Get a summary of the /ws/v1/firmware_updates APIs.
GET, POST	/ws/v1/firmware_updates/inventory	Get a list of latest firmware updates for all devices or run a new firmware update.	orderby cursor size query
GET	/ws/v1/firmware_updates/inventory/{device_id}	Get the latest firmware update for a device.
GET, DELETE	/ws/v1/firmware_updates/history/{device_id}	Get a list of all firmware updates for a device or delete them.	cursor size
GET	/ws/v1/firmware_updates/progress/{device_id}	Get the progress information of the latest firmware update for a device.
POST	/ws/v1/firmware_updates/cancel/{device_id}	Cancel the current firmware update for a device.

Parameters

Name	Type	Description
size	integer	Number of items to return. The maximum and default is 1000.
query	string	The Remote Manager query language query condition used to filter results. See v1 API Query Language.
cursor	string	Cursor to get the next page of devices. Omit on initial call.
orderby	string	Specify any field described in the query parameter syntax. Optionally add `asc` or `desc` to control the sort order. For example, to order with most recently created jobs first, specify orderby=id desc. Note The default sort order is desc (descending).

List firmware update

The following sample request obtains the details of the latest firmware update of a device.

Request

GET /ws/v1/firmware_updates/inventory/00000000-00000000-0040FFFF-FF654321

Response

{
    "id": 1,
    "device_id": "00000000-00000000-0040FFFF-FF654321",
    "customer_id": 1977,
    "start_time": "2021-02-22T09:58:40.070Z",
    "end_time": "2021-02-22T10:02:54.020Z",
    "status": "failed",
    "version": "17.4.1.7",
    "error_message": "Device Not Connected"
}

The response contains the following properties:

id - Unique identifier of the firmware update.
device_id - Unique identifier of the device associated to the firmware update.
custormer_id - Unique customer ID for the Remote Manager customer.
start_time - Time at which the firmware update started.
end_time - Time at which the firmware update ended.
status - The status of the firmware update process. One of:
- active
- waiting
- successful
- failed
- canceled
- starting
version - Firmware version being applied in the firmware update process.
file - File used to update the device in case a file was used instead of a version.
error_message - If the status of the firmware update is failed or canceled, this field contains information about the error.

Run firmware update

Single Device

The following sample request executes a firmware update on the provided device.

Request

POST /ws/v1/firmware_updates/inventory

Payload

{
    "targets": {
        "devices": [
            "00000000-00000000-0040FFFF-FF123456"
        ]
    },
    "version": "17.4.1.7"
}

Single Group

The following sample request executes a firmware update on the provided group.

Request

POST /ws/v1/firmware_updates/inventory

Payload

{
    "targets": {
        "groups": [
            "group1"
        ]
    },
    "version": "17.4.1.7"
}

Request payload

To execute a new firmware update, include the following elements in the body of your POST request:

targets - Specifies the devices to be updated. If multiple elements are provided, they are combined using an OR operation. This means that if you include both tags and groups, devices that belong to the specified group OR have the specified tag will be updated. They can be specified with the following elements:
- devices - List with the IDs of the devices to update.
- tags - List with the tag names the devices to update are labeled with.
- groups - List with the name of the groups containing the devices to update.
version - The firmware version to use for the update.
file - The name of the file from a fileset to use for the update.

Info

You can mix devices, tags and groups elements in the same request, but only one of version or file must be specified.

Response

{
    "count": 3,
    "size": 1000,
    "list": [
        {
            "device_id": "00000000-00000000-0040FFFF-FF123456",
            "error": "Invalid target. Device not found"
        },
        {
            "device_id": "00000000-00000000-0040FFFF-FF654321",
            "id": 1
        },
        {
            "device_id": "00000000-00000000-0040FFFF-FF112233",
            "id": 2
        }
    ]
}

Get firmware update progress

The following sample request gets the update progress of the latest firmware update of a device.

Request

GET /ws/v1/firmware_updates/progress/00000000-00000000-0040FFFF-FF112233

Response

{
    "id": 2,
    "customer_id": 1977,
    "device_id": "00000000-00000000-0040FFFF-FF112233",
    "progress": [
        {
            "status": 0,
            "time": "2021-02-22T09:58:40.070Z",
            "message": "Getting Target Info"
        },
        {
            "status": 0,
            "time": "2021-02-22T09:58:41.070Z",
            "message": "Sending Download Request"
        },
        {
            "status": 5,
            "time": "2021-02-22T09:58:42.070Z",
            "message": "Sending Data: 23552 out of 461657 bytes sent"
        },
        {
            "status": 10,
            "time": "2021-02-22T09:58:59.070Z",
            "message": "Sending Data: 47104 out of 461657 bytes sent"
        }
    ]
}

The response contains the following properties:

id - Unique identifier of the firmware update progress.
custormer_id - Unique customer ID for the Remote Manager customer.
device_id - Unique identifier of the device associated to the firmware update progress.
progress - List containing the different progress entries of the firmware update. Each entry is defined by the following elements:
- status - Total update progress percentage completed with the entry.
- time - Date at which the progress entry was generated.
- message - Message containing progress entry information.

Cancel firmware update

The following sample request cancels the firmware update running on a device.

Request

POST /ws/v1/firmware_updates/cancel/00000000-00000000-0040FFFF-FF112233

Response

This request does not return a response unless there is an error.