Skip to content
Spoke Zone Docs

OTA File Downloads

This page outlines how devices can find and download Over-the-Air (OTA) files using the v2 API.

Workflow for Downloading OTA Files

  1. Get Available OTA Files:

    • Use the GET /api/v2/ota-files endpoint to retrieve a list of available OTA files for the device.
    • Filter results using query parameters:
      • module — Filter by module token (e.g., ?module=display-app).
      • isActive — Filter to only active files (e.g., ?isActive=1).
    • In most cases, a device should query with both parameters to get only active files for the relevant module (e.g., /api/v2/ota-files?module=display-app&isActive=1). Devices can only download active files — attempting to download an inactive file will return a 404 error.

  2. Find the Required OTA File:

    • Review the response, which is in JSON format including the id, version, module and other corresponding metadata for each OTA file.
    • Identify the file you want to download based on the desired version.
      • Your application can automatically determine which version to install, or prompt the user to select one.

  3. Download the OTA File:

    • Use the GET /api/v2/ota-files/:id/file endpoint, replacing :id with the id of the desired OTA file.
    • The server will respond with the OTA file as a binary, ready for installation on the device.
    • If the file is not active, the server will respond with a 404 error.
    • It is the responsibility of the device to handle installing the binary correctly.

Example

1. Get All OTA Files

Request:

GET /api/v2/ota-files?module=display-app&isActive=1
Headers:
  x-access-token: <your_device_token>

Response:

[
  { "id": "12345", "version": "1.2.3", "module": "display-app", "isActive": true, ... },
  { "id": "67890", "version": "1.3.0", "module": "display-app", "isActive": true, ... },
  ...
]

2. Download Specific OTA File

Request:

GET /api/v2/ota-files/12345/file
Headers:
  x-access-token: <your_device_token>

Response: Binary OTA file content.

Migrating From the v1 API

  1. Replace /api/v1/deviceUser/read-only/models/firmware with /api/v2/ota-files to retrieve the list of available OTA files.
  • Please note that the fields have changed.
    • For example, id instead of firmware_id and version instead of version_number.
  1. Replace /api/v1/deviceUser/read-only/models/firmware/:id with /api/v2/ota-files/:id/file to download a specific OTA file.