Firmware Management API

API usage

Firmware management API is a standard HTTP JSON API. Request and response bodies are formatted as JSON.

Common errors

404 - Not found: Requested path does not exist
405 - Method not allowed: HTTP method for the requested path is not supported
429 - Too many requests: Rate limit exceeded
415 - Unsupported media type: Accept or Content-Type header is missing or unsupported for the request
5xx - Server side errors: If server has failures

Get Firmware Updates

POST /api/v1/firmware-update/check

Endpoint returns a new firmware for the given device, if available.

Request details

Required headers
Name	Description
`Accept`	Set to application/json.
`Content-Type`	Set to application/json.

Request JSON object body
Path	Type	Description
`clientId`	`String`	Client ID string.
`uuid`	`String`	Device UUID in string format.
`firmwareVersion`	`String`	Firmware version in semantic version string form.
`hardwareCode`	`String`	Device hardware code / erp number as string.

Response details

Response status codes

200 - OK: when request is valid and new firmware is available
204 - NO_CONTENT: when request is valid and there are no new firmwares available
400 - BAD_REQUEST: when request is invalid

Response body JSON fields on success case
Path	Type	Description
`id`	`Number`	Firmware ID.
`created`	`String`	Firmware creation date in ISO 8601 format.
`modified`	`String`	Firmware last modification date in ISO 8601 format.
`description`	`String`	Firmware description.
`erpNumber`	`String`	Firmware ERP number.
`version`	`String`	Firmware version.
`fileUrl`	`String`	Firmware file download URL.
`baseUrl`	`String`	Firmware base URL. Used with combination of languageFiles
`lifeCycle`	`String`	Firmware life cycle status.
`languageFiles`	`Array`	Firmware language files postfix to be used with baseUrl.
`hardwareVersions`	`Array`	Firmware hardware compatibility info.
`hardwareVersions[].expired`	`Boolean`	Hardware version expired status.
`hardwareVersions[].mandatory`	`Boolean`	Hardware version mandatory status.
`hardwareVersions[].erpNumber`	`String`	Hardware version ERP number.
`hardwareVersions[].dependantVersion`	`String`	Hardware version dependant version.
`hardwareVersions[].lifeCycle`	`String`	Hardware version life cycle status.

Examples

When new firmware is available

Curl request

$ curl 'https://firmware-management.polar.com/api/v1/firmware-update/check' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "clientId" : "<client id string>",
  "uuid" : "0e030000-0084-0000-0000-000001234565",
  "firmwareVersion" : "1.2.3",
  "hardwareCode" : "00748648.00"
}'

HTTP response

HTTP/1.1 200 OK
Date: Wed, 04 Dec 2024 07:24:31 GMT
Content-Type: application/json

{
  "id" : 123,
  "created" : "2024-12-04T07:24:31.339007134Z",
  "modified" : "2024-12-04T07:24:31.339007735Z",
  "description" : "Polar_INW5B 2.0.10",
  "erpNumber" : "710113006.00",
  "version" : "1.2.3",
  "fileUrl" : "https://cdn.polar.com/firmware/2e88bd75-d822-41dc-bf0b-d3a3322e83be/firmware.zip",
  "baseUrl" : "https://cdn.polar.com/firmware/2e88bd75-d822-41dc-bf0b-d3a3322e83be/",
  "lifeCycle" : "R",
  "languageFiles" : [ "lang_ja.zip", "lang_zh.zip", "langs.zip" ],
  "hardwareVersions" : [ {
    "expired" : false,
    "mandatory" : true,
    "erpNumber" : "00748648.01",
    "dependantVersion" : "1.2.4",
    "lifeCycle" : "Launched"
  } ]
}

When there are no new firmwares available

Curl request

$ curl 'https://firmware-management.polar.com/api/v1/firmware-update/check' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "clientId" : "<client id string>",
  "uuid" : "0e030000-0084-0000-0000-000001234565",
  "firmwareVersion" : "1.2.3",
  "hardwareCode" : "00748648.00"
}'

HTTP response

HTTP/1.1 204 No Content
Date: Wed, 04 Dec 2024 07:24:31 GMT

When invalid input given

Curl request

$ curl 'https://firmware-management.polar.com/api/v1/firmware-update/check' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "clientId" : "foo",
  "uuid" : "0e030000-0084-0000-0000-000001234565",
  "firmwareVersion" : "1.2.3",
  "hardwareCode" : "00748648.00"
}'

HTTP response

HTTP/1.1 429 Too Many Requests
Date: Wed, 04 Dec 2024 07:24:31 GMT
Content-Type: application/json

Rate limit has been exceeded