v1/firmware

Use the v1/firmware API to list, search, and download Digi device firmware and modem firmware.

You can also use the v1/firmware API to create, list, update or remove custom firmware. This can be useful in products where Digi does not provide firmware or if you want to provide your own firmware and use it the same way as other Digi firmware, even in Automations or Configurations.

Info

Each user can store up to 10 GB of custom firmware. After reaching this limit, you will not be allowed to upload more custom firmware until you delete any image. If you need more space, please contact a Digi representative.

Some notes about these APIs:

  • Some of these APIs are available to an un-authenticated caller, other APIs require authentication or have features which require authentication. For example, setting the include_non_production parameter to true, requires that you have the permission to view non-production firmware, so an authenticated call is required.
  • These APIs are also available using the firmware.devicecloud.com hostname. It is recommended you use the firmware.devicecloud.com hostname to access these APIS. Using this hostname will isolate you from future changes in firmware hosting infrastructure.
  • The APIs for fetching firmware often redirect to another location. You should follow the redirect to get the firmware image.
  • The APIs for listing firmware often return a secure, signed and expiring link. You can safely share this link to download the firmware image, but the link will usually expire in 24 hours.

URI

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

Formats

HTTP method Format Description Authentication Required Required Parameter Parameters
GET /ws/v1/firmware Get summary of the device APIs. Yes
GET /ws/v1/firmware/download/{model_name}/{firmware_version}/{filename} Download the firmware image. No
GET /ws/v1/firmware/inventory List Digi device firmware, custom firmware or modem firmware. Yes size query cursor orderby firmware_type device_filtered
GET /ws/v1/firmware/inventory/{vendor_id} List firmware of the given internal device type No device_type_internal size query cursor orderby firmware_type device_filtered device_type_internal firmware_version artifact_id get_all_artifacts include_non_production include_deprecated production deprecated filename information_link security_related sha_512 sha3_512 shared
GET, POST, PUT, DELETE /ws/v1/firmware/inventory/{vendor_id}/{device_type} List firmware and create, update or delete custom firmware. No Various depending on method firmware_version artifact_id get_all_artifacts include_non_production include_deprecated device_type_internal production deprecated filename information_link security_related sha_512 sha3_512 shared
POST /ws/v1/firmware/inventory_with_list List firmware of the given vendor IDs and device types. No size cursor include_non_production include_deprecated
GET /ws/v1/firmware/list List only the firmware version numbers available for the model No model_name production deprecated
GET /ws/v1/firmware/{version} Get firmware information for a specific version and model name. No model_name
GET /ws/v1/firmware/{version}/firmware_url Return a limited set of info about firmware, including the URL No model_name

Payloads

The inventory_with_list API accepts a payload to filter the returned list. Specify one or more vendor IDs and device types to filter the list. The payload is a JSON array of objects with the following fields:

[{
    "vendor_id": "FE00000A",
    "device_type": "Digi EX15"
},
{
  "vendor_id": "FE00000A",
  "device_type": "Digi TX64"
}]

Path Parameters

These parameters are required in the URL path of some API calls.

Name Type Description
device_type string The device type of the firmware. Requires encoding special characters (link blanks) correctly.
filename string Usually optional, but might be required for the client calling the API so that the file can be saved locally.
model_name string Usually the same as the device type, but requires representing blanks as a slash (/) character, creating a new URL path component. For example: GET https://firmware.devicecloud.com/ws/v1/firmware/download/Digi/EX15/22.11.48.10/test.bin where Digi EX15 is the model name
vendor_id string The vendor ID of the firmware in hex. For example, Devices running DAL OS usually have a vendor ID of FE00000A, so the list request is GET https://firmware.devicecloud.com/ws/v1/firmware/inventory/FE00000A/Digi%20TX64

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).
firmware_type string Specify the type of the firmware to get: device (Digi device firmware), custom (customer uploaded firmware) or modem (modem firmware). If no type is provided, it defaults to device.
device_type_internal string The hex value representing the XBee hardware version. Usually this is just the upper byte of the hardware version
device_filtered boolean true to only get firmware that match the vendor ID and device type of the devices added to your account, false to get all firmware. It defaults to false.
firmware_version string The version of the firmware following the format X.X.X.X (X between 0 and 255).
artifact_id string The artifact ID of the firmware. Do not specify the artifact ID for the main firmware image, that is, the image that will be sent to the device.
get_all_artifacts boolean true to get all artifacts for each firmware version, false to only get the main image. It defaults to false.
include_non_production boolean true to include non-production firmware in the list, false to only get production firmware. It defaults to false. Your account must be enabled to view non-production (pre-release) firmware. Contact customer support for more info.
include_deprecated boolean true to include deprecated firmware in the list, false to only get non-deprecated firmware. It defaults to false. Your account must be enabled to view deprecated (removed from public) firmware. Contact customer support for more info.
device_type_internal integer The device type internal (hardware version) of the firmware, from 0x00 to 0xFF. Only applicable for XBee firmware.
production boolean true to mark the firmware as production, false to mark it as non-production. It defaults to true.
deprecated boolean true to mark the firmware as deprecated, false to mark it as non-deprecated. It defaults to false.
filename string The filename of the firmware. If no filename is provided, <device_type>-<firmware_version>.bin is used.
information_link string URL of the firmware release notes.
security_related string The CVSS score of the firmware: not-identified, none, low, medium, high or critical.
sha_512 string The SHA-512 of the firmware. If no SHA-512 is provided, it is calculated automatically.
sha3_512 string The SHA3-512 of the firmware. If no SHA3-512 is provided, it is calculated automatically.
shared string A comma-separated list of subaccount customer IDs to share the custom firmware with. It can also be all to share the firmware with all subaccounts. If no shared is provided, the firmware is not shared with any subaccount.