API Reference

The MQCentral API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Getting Started

To begin using the API, you'll need a Client ID and Client Secret. Follow the steps in our Authentication & API Access guide to make your first request.

Base URL

https://fuota.machineq.net

Authentication

The MQCentral API uses bearer tokens to authenticate requests. To get a bearer token, you need to use your account's Client ID and Client Secret to authenticate through the "get token" API. A successful response will include your bearer token, which you must include with every API request you make.

Your client credentials carry many privileges, so be sure to keep them secure! Do not share your secret Client ID and Client Secret in publicly accessible areas such as GitHub, client-side code, and so forth.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Authenticated Request

curl https://fuota.machineq.net/v1/endpoint \
  -H "Authorization: Bearer eyJhbGciSR5cC...kpXVCIstpZeGYeVg" \
  -H "Content-Type: application/json"

Errors

MQCentral uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Code in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a parameter key was spelled wrong, etc.). Codes in the 5xx range indicate an error with MQCentral's servers (these are rare).

Some 4xx errors that could be handled programmatically include an error code that briefly explains the error reported.

HTTP Error Codes

                
                        200
                        OK
                        Everything worked as expected.
                    
                        400
                        Bad Request
                        The request was unacceptable, often due to missing a required parameter.
                    
                        401
                        Unauthorized
                        No valid Client Credential provided.
                    
                        402
                        Request Failed
                        The parameters were valid but the request failed.
                    
                        403
                        Forbidden
                        The bearer token doesn’t have permissions to perform the request.
                    
                        404
                        Not Found
                        The requested resource doesn’t exist.
                    
                        409
                        Conflict
                        The request conflicts with another request (perhaps due to using the same idempotent
                            key).
                        
                        424
                        External Dependency Failed
                        The request couldn’t be completed due to a failure in a dependency external to
                            MQCentral.
                        
                        429
                        Too Many Requests
                        Too many requests hit the API too quickly. We recommend an exponential backoff of
                            your requests.
                        
                        500, 502, 503, 504
                        Server Errors
                        Something went wrong on MQCentral’s end. (These are rare.)

200	OK	Everything worked as expected.
400	Bad Request	The request was unacceptable, often due to missing a required parameter.
401	Unauthorized	No valid Client Credential provided.
402	Request Failed	The parameters were valid but the request failed.
403	Forbidden	The bearer token doesn’t have permissions to perform the request.
404	Not Found	The requested resource doesn’t exist.
409	Conflict	The request conflicts with another request (perhaps due to using the same idempotent key).
424	External Dependency Failed	The request couldn’t be completed due to a failure in a dependency external to MQCentral.
429	Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504	Server Errors	Something went wrong on MQCentral’s end. (These are rare.)

Campaigns

Manages firmware update campaigns, including creation, monitoring, and deletion.

Endpoints

                GET/v3.2/campaigns
POST/v3.2/campaigns
GET/v3.2/campaigns/bulk-status
GET/v3.2/campaigns/{campaign_id}
DELETE/v3.2/campaigns/{campaign_id}

            

The Campaigns object

Attributes

campaign_id string

Unique identifier of the campaign.

image_name string

Name of the firmware image used by this campaign.

name string

Human-readable label for the campaign.

device_group_id string

Identifier of the device group targeted by this campaign.

status string

Free-text status message. Empty when no notable status exists.

created_at string (date-time)

Timestamp when the campaign was created, in RFC 3339 format.

scheduled_start_at string(date-time) | null

Scheduled start time in RFC 3339 format. Null if the campaign starts immediately.

stage integer

Integer representation of the stage. For complete list see stage of the campaign schema

stage_str string

String representation of the stage. For complete list see stage of the campaign schema

num_devices_success integer

Number of devices that have successfully updated.

num_devices_fail integer

Number of devices that failed to update.

num_devices_in_progress integer

Number of devices still in progress or setting up.

The Campaigns object

{
  "campaign_id": "string",
  "image_name": "string",
  "name": "string",
  "device_group_id": "string",
  "status": "string",
  "created_at": "2006-01-02T15:04:05.000Z",
  "scheduled_start_at": "2006-01-02T15:04:05.000Z",
  "stage": 0,
  "stage_str": "string",
  "num_devices_success": 0,
  "num_devices_fail": 0,
  "num_devices_in_progress": 0
}

Retrieves all campaigns

Retrieves all campaigns for the authenticated subscriber. Returns a list of campaign summary objects including stage, device counts, and scheduling information.

Body Parameters

No parameters.

Returns

× 200 List of campaign summary objects for the authenticated subscriber. application/json

[
  {
    "campaign_id": "XgAEtg",
    "created_at": "2023-01-21T18:51:28.469107Z",
    "device_group_id": "poiuyt",
    "name": "Fuota v3.0.0",
    "num_devices_fail": 0,
    "num_devices_in_progress": 10,
    "num_devices_success": 0,
    "scheduled_start_at": "2024-01-23T19:57:55.628Z",
    "stage": 0,
    "stage_str": "INITIALIZING",
    "status": ""
  },
  {
    "campaign_id": "abcdef",
    "created_at": "2026-01-21T00:00:00.000000Z",
    "device_group_id": "tgbyhn",
    "name": "Some campaign",
    "num_devices_fail": 5,
    "num_devices_in_progress": 0,
    "num_devices_success": 5,
    "scheduled_start_at": "2026-01-21T01:00:00.000Z",
    "stage": 7,
    "stage_str": "FINISHED",
    "status": ""
  }
]

array of objects

List of campaign summary objects.

GET /v3.2/campaigns

curl 'https://fuota.machineq.net/api/v3.2/campaigns'

Creates a new campaign

Creates a new firmware update campaign or schedules one for later execution. Returns 202 with a partial campaign status while initialization is in progress.

name — a human-readable label for the campaign.
image_name — name of the firmware image previously uploaded via /images.
device_group_id — identifier of the target device group, created via /device_groups/keygen or /device_groups.
expected_version — expected firmware version after the update. Accepts a semantic version string (e.g., 0.1.2.3 or 1.2.3) or a 16-character hex pattern. (See hex pattern documentation). Inferred from image_name when omitted.
multicast_setup_time — (optional) multicast setup window in seconds. Automatically determined in most cases. Consult the documentation.

Body Parameters

name string required

Human-readable label for the campaign.

image_name string required

Name of the firmware image previously uploaded via /images.

device_group_id string required

Identifier of the target device group.

mcast_deveui string | null

Multicast DevEUI. Auto-generated when omitted. If provided, mcast_devaddr and mcast_mc_key must also be set.

mcast_dr integer

Multicast data rate. Allowed values: 1-14.

mcast_freq float

Multicast frequency in MHz. Must be between 0 and 1000 exclusive.

mcast_session_timeout integer | null

Multicast session timeout in seconds. Must be a power of 2. Null lets the server choose automatically.

redundancy float

Fraction of redundancy fragments to send, from 0.0 (none) to 1.0 (100%).

expected_version string | null

Expected firmware version after the update (e.g., '0.1.2.3'). Inferred from image_name when omitted.

frag_send_delay float

Delay between sending each fragment, in seconds.

acceptable_time_drift integer

Maximum acceptable clock drift between server and device, in seconds.

sleep_after_frag_sent integer

Wait time after all fragments are sent before proceeding, in seconds.

descriptor string

8-character hex descriptor for the firmware image.

min_downlink_delay float

Minimum delay between consecutive downlinks to a device, in seconds.

min_timeout_delay float

Minimum timeout before retrying a downlink, in seconds. Must be greater than min_downlink_delay.

force_initial_version_check boolean

Whether to verify the device firmware version before starting the update. True means the version check is enforced.

completed_email_alert array of strings

Reserved. Currently unused.

max_final_version_check_retry integer

Maximum number of retries for the final firmware version check.

automatic_retry_count integer

Number of automatic retries for failed devices. 0 disables automatic retries.

automatic_retry_interval integer

Interval between automatic retries, in seconds.

downlink_delay_rand_s integer

Maximum random jitter added to downlink delays, in seconds. 0 disables jitter.

individual_fragment_retransmit integer

Number of individual fragment retransmissions per device. 0 disables individual retransmission. Experimental.

multicast_setup_time integer | null

Multicast setup window in seconds. Auto-determined when omitted.

scheduled_start_at string(date-time) | null

Scheduled start time in RFC 3339 format. Must be in the future. Null starts the campaign immediately.

mcast_devaddr string | null

Multicast device address. Required when mcast_deveui is provided.

mcast_mc_key string | null

Multicast session key (32-character hex). Required when mcast_deveui is provided.

is_debug boolean

Whether to collect debug information for each device. True enables debug logging in the campaign response.

is_troubleshooting boolean

Whether to run automated troubleshooting checks on each device. True enables troubleshooting output in the campaign response.

Examples

Returns

× 202 Partial campaign status returned while initialization is in progress. application/json

{
  "campaign_id": "XgAEtg",
  "created_at": "2023-01-21T18:51:28.469107Z",
  "name": "Fuota v3.0.0",
  "scheduled_start_at": "2024-01-23T19:57:55.628Z",
  "stage": 0,
  "stage_str": "INITIALIZING",
  "status": ""
}

campaign_id string

Unique identifier of the campaign.

name string

Human-readable label for the campaign.

status string

Free-text status message. Empty when no notable status exists.

created_at string (date-time)

Timestamp when the campaign was created, in RFC 3339 format.

scheduled_start_at string(date-time) | null

Scheduled start time in RFC 3339 format. Null if the campaign starts immediately.

stage enum (integer)

Campaign stages:

INITIALIZING (0): campaign was created by the state was not initialized yet
DELAYED_START (1): campaign was created with a delayed start time
SETTING_UP_DEVICES (2): the server is setting up the devices
SENDING_FRAGMENTS (3): the server is sending fragments
FRAG_SEND_DELAY (4): the server is waiting for the fragment send delay to pass. Gives devices time to process the fragments and restart.
FINAL_VERSION_CHECK (5): the server is checking that all devices have the expected version
RETRY_SCHEDULED (6): either campaign is scheduled to retry. Triggered manually or automatically on failure.
FINISHED (7): campaign finished. Either success or failure.
ERROR_SETTING_UP (8): campaign failed to set up. Mostly related to error while creating the multicast group or gateway tagging.
DELETING (9): campaign is being deleted.
DELETE_ERROR (10): campaign deletion failed.

stage_str string

String representation of the stage. For complete list see stage of the campaign schema

Body

{
  "name": "string",
  "image_name": "string",
  "device_group_id": "string",
  "mcast_deveui": "string",
  "mcast_dr": 0,
  "mcast_freq": 0.0,
  "mcast_session_timeout": 0,
  "redundancy": 0.0,
  "expected_version": "string",
  "frag_send_delay": 0.0,
  "acceptable_time_drift": 0,
  "sleep_after_frag_sent": 0,
  "descriptor": "string",
  "min_downlink_delay": 0.0,
  "min_timeout_delay": 0.0,
  "force_initial_version_check": true,
  "completed_email_alert": [
    "string"
  ],
  "max_final_version_check_retry": 0,
  "automatic_retry_count": 0,
  "automatic_retry_interval": 0,
  "downlink_delay_rand_s": 0,
  "individual_fragment_retransmit": 0,
  "multicast_setup_time": 0,
  "scheduled_start_at": "2006-01-02T15:04:05.000Z",
  "mcast_devaddr": "string",
  "mcast_mc_key": "string",
  "is_debug": true,
  "is_troubleshooting": true
}

POST /v3.2/campaigns

curl -X POST 'https://fuota.machineq.net/api/v3.2/campaigns'

Retrieves statuses for multiple campaigns

Retrieves status information for multiple campaigns in a single request. Returns a dictionary keyed by campaign ID, where each value is an array of [stage, successful_device_count, total_device_count].

Query Parameters

campaign_ids array required

List of campaign IDs to retrieve. Supports comma-separated values in a single query parameter.

Body Parameters

No parameters.

Returns

Query Parameters

GET /v3.2/campaigns/bulk-status

curl 'https://fuota.machineq.net/api/v3.2/campaigns/bulk-status'

Retrieves a specific campaign

Retrieves the full campaign state for the given campaign ID. Returns 202 while the campaign is still initializing. Debug and troubleshooting information is included only when the respective flags are enabled.

Path Parameters

campaign_id string required

Unique identifier of the campaign.

Body Parameters

No parameters.

Returns

× 200 Full campaign state including all device statuses and progress information. application/json

{
  "acceptable_time_drift": 40,
  "attempts": 1,
  "automatic_retry_count": 0,
  "automatic_retry_interval": 120,
  "campaign_id": "XgAEtg",
  "class_c_start_at": "2023-10-17T20:53:46.893534Z",
  "completed_email_alert": [],
  "created_at": "2023-10-13T14:56:48.464374Z",
  "current_fragment_cnt": 0,
  "data_fragments": 67,
  "delayed_start": 0,
  "descriptor": "00000000",
  "device_group_id": "tEgdxH",
  "devices": [
    {
      "attempts": 0,
      "deveui": "2CC407FFFE5171AA",
      "lora_class": "A",
      "ready_for_fragments_at": "2023-10-17T20:44:48.580644Z",
      "reason": "",
      "session_start_at": 1697576027,
      "stage": 5,
      "stage_str": "FAIL",
      "troubleshooting": {
        "checks": [
          {
            "details": "Device appears offline. Last uplink was at 2025-01-01 12:00:00",
            "id": 1,
            "name": "Device online",
            "result": "FAIL"
          }
        ],
        "summary": "Device was offline during the entire campaign."
      }
    }
  ],
  "downlink_delay_rand_s": 10,
  "estimated_frags_complete": "2023-10-17T20:58:02.893534Z",
  "expected_version": "0.2.0.0",
  "force_initial_version_check": true,
  "frag_send_delay": 2,
  "gateways": [
    "1122334455667788"
  ],
  "image_name": "fuota_v3.0.0.bin",
  "individual_fragment_retransmit": 0,
  "max_final_version_check_retry": 15,
  "mcast_deveui": "EDC1ECE9EDC1ECE9",
  "mcast_dr": 11,
  "mcast_freq": 923.9,
  "mcast_session_timeout": 256,
  "min_downlink_delay": 5,
  "min_timeout_delay": 30,
  "name": "Fuota v3.0.0",
  "redundancy": 0.3,
  "redundancy_fragments": 21,
  "retry_success_rates": [],
  "sleep_after_frag_sent": 600,
  "stage": 2,
  "stage_str": "SETTING_UP_DEVICES",
  "start_in": 600,
  "started_at": "2023-10-17T20:43:46.893618Z",
  "total_devices": 1
}

campaign_id string

Unique identifier of the campaign.

stage enum (integer)

Campaign stages:

INITIALIZING (0): campaign was created by the state was not initialized yet
DELAYED_START (1): campaign was created with a delayed start time
SETTING_UP_DEVICES (2): the server is setting up the devices
SENDING_FRAGMENTS (3): the server is sending fragments
FRAG_SEND_DELAY (4): the server is waiting for the fragment send delay to pass. Gives devices time to process the fragments and restart.
FINAL_VERSION_CHECK (5): the server is checking that all devices have the expected version
RETRY_SCHEDULED (6): either campaign is scheduled to retry. Triggered manually or automatically on failure.
FINISHED (7): campaign finished. Either success or failure.
ERROR_SETTING_UP (8): campaign failed to set up. Mostly related to error while creating the multicast group or gateway tagging.
DELETING (9): campaign is being deleted.
DELETE_ERROR (10): campaign deletion failed.

created_at string (date-time)

Timestamp when the campaign was created, in RFC 3339 format.

started_at string(date-time) | null

Timestamp when the campaign started, in RFC 3339 format. Null if not yet started.

finished_at string(date-time) | null

Timestamp when the campaign finished, in RFC 3339 format. Null if not yet finished.

class_c_start_at string | null

Timestamp when Class C fragment transmission begins, in RFC 3339 format. Null for Class A campaigns.

estimated_frags_complete string(date-time) | null

Estimated time when all fragments will be sent, in RFC 3339 format. Null if not yet calculated.

data_fragments integer

Total number of data fragments to transmit.

redundancy_fragments integer

Total number of redundancy fragments to transmit.

gateways array of strings

List of gateway identifiers used by this campaign. Maximum 10 items.

total_devices integer

Total number of devices in the campaign.

retry_success_rates array of integers

List of cumulative successful device counts after each attempt.

attempts integer

Number of update attempts executed so far.

current_fragment_cnt integer

Number of fragments sent so far in the current attempt.

devices array of objects

List of per-device states including troubleshooting results.

× Hide array object attributes

deveui string

Extended Unique Identifier of the device (16-character hex).

stage enum (integer)

Device stages for the FUOTA process:

INIT (0): device state was created but not initialized yet
INITIAL_VERSION_CHECK (1): the server is checking device's initial version
MCAST_GROUP_SETUP (2): the server is setting up the multicast group
FRAG_SETUP (3): the server is setting up the fragmentation session
MCAST_SESSION_SETUP (4): the server is setting up the multicast session
FRAGMENTS (5): the device is set up to receive fragments The fragmentation will be sent at class_c_start_at.
FINAL_VERSION_CHECK (6): the server is checking that the device has the expected version.
SUCCESS (7): the device has the expected version.
FAIL (9): the device failed to update to the expected version.

initial_version string | null

Firmware version reported by the device before the update (16-character hex). Null if not yet reported.

latest_version string | null

Most recently reported firmware version (16-character hex). Null if not yet reported.

lora_class enum (string)

LoRaWAN device class that determines how the FUOTA server sends downlinks. Class A sends all downlinks immediately, queuing them on the network server. Class C sends downlinks one by one, waiting for a response from the device before proceeding to the next step.

session_start_at string(date-time) | number | null

Timestamp when the device joined the multicast session, in RFC 3339 format. Null if the device has not yet joined.

reason string

Human-readable reason for the current device stage. Empty when no notable reason exists.

attempts integer

Number of update attempts made for this device.

ready_for_fragments_at string(date-time) | string | null

Timestamp when the device became ready to receive fragments, in RFC 3339 format. Null if not yet ready.

stage_str string

Human-readable name of the device stage.

debug_info array of objects

Chronological list of debug log entries collected during the update. Empty when debug mode is disabled.

troubleshooting object | null

Troubleshooting results for the device. Null when troubleshooting is disabled for the campaign.

status string

Free-text status message. Empty when no notable status exists.

name string

Human-readable label for the campaign.

image_name string

Name of the firmware image previously uploaded via /images.

device_group_id string

Identifier of the target device group.

mcast_deveui string | null

Multicast DevEUI. Auto-generated when omitted. If provided, mcast_devaddr and mcast_mc_key must also be set.

mcast_dr integer

Multicast data rate. Allowed values: 1-14.

mcast_freq float

Multicast frequency in MHz. Must be between 0 and 1000 exclusive.

mcast_session_timeout integer | null

Multicast session timeout in seconds. Must be a power of 2. Null lets the server choose automatically.

redundancy float

Fraction of redundancy fragments to send, from 0.0 (none) to 1.0 (100%).

expected_version string

Expected firmware version after the update as a 16-character hex mask, where '.' matches any hex digit.

frag_send_delay float

Delay between sending each fragment, in seconds.

acceptable_time_drift integer

Maximum acceptable clock drift between server and device, in seconds.

sleep_after_frag_sent integer

Wait time after all fragments are sent before proceeding, in seconds.

descriptor string

8-character hex descriptor for the firmware image.

min_downlink_delay float

Minimum delay between consecutive downlinks to a device, in seconds.

min_timeout_delay float

Minimum timeout before retrying a downlink, in seconds. Must be greater than min_downlink_delay.

force_initial_version_check boolean

Whether to verify the device firmware version before starting the update. True means the version check is enforced.

max_final_version_check_retry integer

Maximum number of retries for the final firmware version check.

automatic_retry_count integer

Number of automatic retries for failed devices. 0 disables automatic retries.

automatic_retry_interval integer

Interval between automatic retries, in seconds.

downlink_delay_rand_s integer

Maximum random jitter added to downlink delays, in seconds. 0 disables jitter.

individual_fragment_retransmit integer

Number of individual fragment retransmissions per device. 0 disables individual retransmission. Experimental.

stage_str string

Human-readable name of the campaign stage.

multicast_setup_time integer

Multicast setup window in seconds. 0 indicates the server determined the value automatically.

scheduled_start_at string(date-time) | null

Scheduled start time in RFC 3339 format. Null if the campaign was started immediately.

is_debug boolean

Whether debug information is collected for each device. True enables per-device debug_info in the response.

is_troubleshooting boolean

Whether automated troubleshooting checks run on each device. True enables per-device troubleshooting output in the response.

× 202 Campaign is still initializing; returns partial status with campaign ID and current stage. application/json

{
  "campaign_id": "XgAEtg",
  "created_at": "2023-01-21T18:51:28.469107Z",
  "name": "Fuota v3.0.0",
  "scheduled_start_at": "2024-01-23T19:57:55.628Z",
  "stage": 0,
  "stage_str": "INITIALIZING",
  "status": ""
}

campaign_id string

Unique identifier of the campaign.

name string

Human-readable label for the campaign.

status string

Free-text status message. Empty when no notable status exists.

created_at string (date-time)

Timestamp when the campaign was created, in RFC 3339 format.

scheduled_start_at string(date-time) | null

Scheduled start time in RFC 3339 format. Null if the campaign starts immediately.

stage enum (integer)

Campaign stages:

INITIALIZING (0): campaign was created by the state was not initialized yet
DELAYED_START (1): campaign was created with a delayed start time
SETTING_UP_DEVICES (2): the server is setting up the devices
SENDING_FRAGMENTS (3): the server is sending fragments
FRAG_SEND_DELAY (4): the server is waiting for the fragment send delay to pass. Gives devices time to process the fragments and restart.
FINAL_VERSION_CHECK (5): the server is checking that all devices have the expected version
RETRY_SCHEDULED (6): either campaign is scheduled to retry. Triggered manually or automatically on failure.
FINISHED (7): campaign finished. Either success or failure.
ERROR_SETTING_UP (8): campaign failed to set up. Mostly related to error while creating the multicast group or gateway tagging.
DELETING (9): campaign is being deleted.
DELETE_ERROR (10): campaign deletion failed.

stage_str string

String representation of the stage. For complete list see stage of the campaign schema

Path Parameters

GET /v3.2/campaigns/{campaign_id}

curl 'https://fuota.machineq.net/api/v3.2/campaigns/{campaign_id}'

Deletes a campaign asynchronously

Deletes the specified campaign asynchronously and stops the update process if it is running. Returns 202 once the deletion is accepted. This operation is irreversible and does not preserve device update history. Use the /halt endpoint first to preserve history before deleting.

Path Parameters

campaign_id string required

Unique identifier of the campaign.

Body Parameters

No parameters.

Returns

Path Parameters

DELETE /v3.2/campaigns/{campaign_id}

curl -X DELETE 'https://fuota.machineq.net/api/v3.2/campaigns/{campaign_id}'

CampaignTools

Provides campaign lifecycle operations such as restart, halt, and short status retrieval.

Endpoints

                POST/v3.2/campaigns/{campaign_id}/halt
POST/v3.2/campaigns/{campaign_id}/restart
GET/v3.2/campaigns/{campaign_id}/short-status

            

Halt Campaign

Stops the running campaign without deleting its state.

Path Parameters

campaign_id string required

Unique identifier of the campaign.

Body Parameters

No parameters.

Returns

Path Parameters

POST /v3.2/campaigns/{campaign_id}/halt

curl -X POST 'https://fuota.machineq.net/api/v3.2/campaigns/{campaign_id}/halt'

Restarts a campaign for failed devices

Restarts the campaign for devices that failed in a previous attempt. Devices that successfully updated retain their state.

Path Parameters

campaign_id string required

Unique identifier of the campaign.

Body Parameters

gateways array of strings | null

Optional list of gateway IDs to use for the restarted campaign. If omitted or empty, gateways are selected automatically.

multicast_setup_time integer | null

Optional multicast setup time in seconds. If not set, original value preserved. Set to 0 or null to use the automatic value.

scheduled_start_at string(date-time) | null

Optional RFC 3339 timestamp to schedule the campaign restart. Must be in the future.

automatic_retry_count integer | null

Optional number of automatic retry attempts for failed devices. If omitted, the previous value is preserved.

redundancy number | null

Optional fragment redundancy ratio between 0 and 1. If omitted, the previous value is preserved.

Examples

Returns

× 202 Partial campaign status confirming the restart is in progress. application/json

{
  "campaign_id": "XgAEtg",
  "created_at": "2023-01-21T18:51:28.469107Z",
  "name": "Fuota v3.0.0",
  "scheduled_start_at": "2024-01-23T19:57:55.628Z",
  "stage": 0,
  "stage_str": "INITIALIZING",
  "status": ""
}

campaign_id string

Unique identifier of the campaign.

name string

Human-readable label for the campaign.

status string

Free-text status message. Empty when no notable status exists.

created_at string (date-time)

Timestamp when the campaign was created, in RFC 3339 format.

scheduled_start_at string(date-time) | null

Scheduled start time in RFC 3339 format. Null if the campaign starts immediately.

stage enum (integer)

Campaign stages:

INITIALIZING (0): campaign was created by the state was not initialized yet
DELAYED_START (1): campaign was created with a delayed start time
SETTING_UP_DEVICES (2): the server is setting up the devices
SENDING_FRAGMENTS (3): the server is sending fragments
FRAG_SEND_DELAY (4): the server is waiting for the fragment send delay to pass. Gives devices time to process the fragments and restart.
FINAL_VERSION_CHECK (5): the server is checking that all devices have the expected version
RETRY_SCHEDULED (6): either campaign is scheduled to retry. Triggered manually or automatically on failure.
FINISHED (7): campaign finished. Either success or failure.
ERROR_SETTING_UP (8): campaign failed to set up. Mostly related to error while creating the multicast group or gateway tagging.
DELETING (9): campaign is being deleted.
DELETE_ERROR (10): campaign deletion failed.

stage_str string

String representation of the stage. For complete list see stage of the campaign schema

Path Parameters

Body

{
  "gateways": [
    "string"
  ],
  "multicast_setup_time": 0,
  "scheduled_start_at": "2006-01-02T15:04:05.000Z",
  "automatic_retry_count": 0,
  "redundancy": 0.0
}

POST /v3.2/campaigns/{campaign_id}/restart

curl -X POST 'https://fuota.machineq.net/api/v3.2/campaigns/{campaign_id}/restart'

Retrieves an abbreviated campaign status

Retrieves an abbreviated campaign status showing only the most vital state parameters for each device. Returns 202 if the campaign state is not yet ready.

Path Parameters

campaign_id string required

Unique identifier of the campaign.

Body Parameters

No parameters.

Returns

× 200 Abbreviated campaign status with per-device stage, attempt count, and failure reason. application/json

{
  "current_fragment_cnt": 551,
  "devices": [
    {
      "attempts": 1,
      "deveui": "0102030405060708",
      "reason": "",
      "stage": 4,
      "stage_str": "FRAGMENTS"
    },
    {
      "attempts": 1,
      "deveui": "0102030405060708",
      "reason": "Final version check fail",
      "stage": 4,
      "stage_str": "FRAGMENTS"
    }
  ]
}

devices array of objects

List of abbreviated per-device statuses.

current_fragment_cnt integer

Number of fragments sent so far in the current attempt.

× 202 Campaign is still initializing; returns partial status with campaign ID and current stage. application/json

{
  "campaign_id": "XgAEtg",
  "created_at": "2023-01-21T18:51:28.469107Z",
  "name": "Fuota v3.0.0",
  "scheduled_start_at": "2024-01-23T19:57:55.628Z",
  "stage": 0,
  "stage_str": "INITIALIZING",
  "status": ""
}

campaign_id string

Unique identifier of the campaign.

name string

Human-readable label for the campaign.

status string

Free-text status message. Empty when no notable status exists.

created_at string (date-time)

Timestamp when the campaign was created, in RFC 3339 format.

scheduled_start_at string(date-time) | null

Scheduled start time in RFC 3339 format. Null if the campaign starts immediately.

stage enum (integer)

Campaign stages:

INITIALIZING (0): campaign was created by the state was not initialized yet
DELAYED_START (1): campaign was created with a delayed start time
SETTING_UP_DEVICES (2): the server is setting up the devices
SENDING_FRAGMENTS (3): the server is sending fragments
FRAG_SEND_DELAY (4): the server is waiting for the fragment send delay to pass. Gives devices time to process the fragments and restart.
FINAL_VERSION_CHECK (5): the server is checking that all devices have the expected version
RETRY_SCHEDULED (6): either campaign is scheduled to retry. Triggered manually or automatically on failure.
FINISHED (7): campaign finished. Either success or failure.
ERROR_SETTING_UP (8): campaign failed to set up. Mostly related to error while creating the multicast group or gateway tagging.
DELETING (9): campaign is being deleted.
DELETE_ERROR (10): campaign deletion failed.

stage_str string

String representation of the stage. For complete list see stage of the campaign schema

Path Parameters

GET /v3.2/campaigns/{campaign_id}/short-status

curl 'https://fuota.machineq.net/api/v3.2/campaigns/{campaign_id}/short-status'

DeviceGroups

Manages device groups used as targets for firmware update campaigns.

Endpoints

                GET/v3.2/device_groups
POST/v3.2/device_groups
PATCH/v3.2/device_groups/keygen/{device_group_id}/add_devices
GET/v3.2/device_groups/{device_group_id}
PUT/v3.2/device_groups/{device_group_id}
PATCH/v3.2/device_groups/{device_group_id}
DELETE/v3.2/device_groups/{device_group_id}
PATCH/v3.2/device_groups/{device_group_id}/add_devices

            

The DeviceGroups object

Attributes

name string

Human-readable label for the device group.

lora_class enum (string)

LoRaWAN device class that determines how the FUOTA server sends downlinks. Class A sends all downlinks immediately, queuing them on the network server. Class C sends downlinks one by one, waiting for a response from the device before proceeding to the next step.

gateways array of strings

List of gateway NodeIDs assigned to this group. Maximum 10. When empty, gateways are automatically selected.

device_group_id string

Unique identifier of the device group. 6-character alphanumeric string.

devices array of strings

List of DevEUIs belonging to this device group.

The DeviceGroups object

{
  "name": "string",
  "lora_class": "string",
  "gateways": [
    "string"
  ],
  "device_group_id": "string",
  "devices": [
    "string"
  ]
}

Retrieves all device groups

Retrieves a list of all device groups with basic information including ID, name, class, and devices.

Body Parameters

No parameters.

Returns

× 200 List of device group objects with ID, name, class, and device details. application/json

[
  {
    "device_group_id": "123456q",
    "devices": [
      "0102030405060708",
      "0102030405060709"
    ],
    "lora_class": "A",
    "name": "My Device Group"
  },
  {
    "device_group_id": "abcabca",
    "devices": [
      "010203040506070a",
      "010203040506070b"
    ],
    "lora_class": "C",
    "name": "My Other Device Group"
  }
]

[
  {
    "device_group_id": "123456q",
    "devices": [
      "0102030405060708",
      "0102030405060709"
    ],
    "lora_class": "A",
    "name": "My Device Group"
  }
]

array of objects

List of device group summary objects.

GET /v3.2/device_groups

curl 'https://fuota.machineq.net/api/v3.2/device_groups'

Creates a device group

Creates a device group. The devices field is a list of DevEUIs. Keys for the DevEUIs can be uploaded separately via /key_management.

Gateways may optionally be provided; otherwise the FUOTA server automatically assigns gateways based on the best gateway for the provided devices. A maximum of ten gateway NodeIDs per group is allowed.

lora_class accepts "A" or "C". When omitted or set to null, the FUOTA server automatically determines the LoRaWAN class from the devices in the group. Device groups with mixed device classes are disallowed.

Body Parameters

name string required

Human-readable label for the device group.

lora_class enum (string) | null

LoRaWAN device class that determines downlink behavior. A: sends all downlinks immediately, queuing them on the network server. C: sends downlinks one by one, waiting for a device response before proceeding. When omitted or null, automatically determined from the devices in the group.

gateways array of strings

List of gateway NodeIDs assigned to this group. Maximum 10. When empty, gateways are automatically selected.

devices array of strings required

List of 16-character hexadecimal DevEUIs to include in the group.

Examples

Returns

Body

{
  "name": "string",
  "lora_class": "string",
  "gateways": [
    "string"
  ],
  "devices": [
    "string"
  ]
}

POST /v3.2/device_groups

curl -X POST 'https://fuota.machineq.net/api/v3.2/device_groups'

Adds devices to a device group with keygen

Adds devices to an existing device group using automatic key generation. The devices field is a list of DevEUIs. Only the "machineq" keygen_type is currently supported.

Path Parameters

device_group_id string required

Unique identifier of the device group. 6-character alphanumeric string.

Body Parameters

keygen_type enum (string) required

Supported key generation algorithms for deriving device GenAppKeys during FUOTA.

devices array of strings required

List of 16-character hexadecimal DevEUIs to add to the group.

Examples

Returns

Path Parameters

Body

{
  "keygen_type": "string",
  "devices": [
    "string"
  ]
}

PATCH /v3.2/device_groups/keygen/{device_group_id}/add_devices

curl -X PATCH 'https://fuota.machineq.net/api/v3.2/device_groups/keygen/{device_group_id}/add_devices'

Retrieves a device group

Retrieves a single device group by device_group_id.

Path Parameters

device_group_id string required

Unique identifier of the device group. 6-character alphanumeric string.

Body Parameters

No parameters.

Returns

Path Parameters

GET /v3.2/device_groups/{device_group_id}

curl 'https://fuota.machineq.net/api/v3.2/device_groups/{device_group_id}'

Replaces a device group

Replaces the device group identified by device_group_id with the provided data.

Path Parameters

device_group_id string required

Unique identifier of the device group. 6-character alphanumeric string.

Body Parameters

name string required

Human-readable label for the device group.

lora_class enum (string) | null

LoRaWAN device class that determines downlink behavior. A: sends all downlinks immediately, queuing them on the network server. C: sends downlinks one by one, waiting for a device response before proceeding. When omitted or null, automatically determined from the devices in the group.

gateways array of strings

List of gateway NodeIDs assigned to this group. Maximum 10. When empty, gateways are automatically selected.

devices array of strings required

List of 16-character hexadecimal DevEUIs to include in the group.

Examples

Returns

Path Parameters

Body

{
  "name": "string",
  "lora_class": "string",
  "gateways": [
    "string"
  ],
  "devices": [
    "string"
  ]
}

PUT /v3.2/device_groups/{device_group_id}

curl -X PUT 'https://fuota.machineq.net/api/v3.2/device_groups/{device_group_id}'

Updates a device group partially

Updates the device group identified by device_group_id with partial data. Only provided fields are modified.

Path Parameters

device_group_id string required

Unique identifier of the device group. 6-character alphanumeric string.

Body Parameters

name string

Human-readable label for the device group.

lora_class enum (string) | null

LoRaWAN device class that determines downlink behavior. A: sends all downlinks immediately, queuing them on the network server. C: sends downlinks one by one, waiting for a device response before proceeding. When omitted or null, automatically determined from the devices in the group.

gateways array of strings

List of gateway NodeIDs assigned to this group. Maximum 10. When empty, gateways are automatically selected.

devices array of strings

List of 16-character hexadecimal DevEUIs to include in the group.

Examples

Returns

Path Parameters

Body

{
  "name": "string",
  "lora_class": "string",
  "gateways": [
    "string"
  ],
  "devices": [
    "string"
  ]
}

PATCH /v3.2/device_groups/{device_group_id}

curl -X PATCH 'https://fuota.machineq.net/api/v3.2/device_groups/{device_group_id}'

Deletes a device group

Deletes the device group identified by device_group_id. Fails if any campaign is still associated with the group; delete the campaign first.

Path Parameters

device_group_id string required

Unique identifier of the device group. 6-character alphanumeric string.

Body Parameters

No parameters.

Returns

Path Parameters

DELETE /v3.2/device_groups/{device_group_id}

curl -X DELETE 'https://fuota.machineq.net/api/v3.2/device_groups/{device_group_id}'

Adds devices to a device group

Adds devices to an existing device group. The devices field is a list of DevEUIs.

Path Parameters

device_group_id string required

Unique identifier of the device group. 6-character alphanumeric string.

Body Parameters

devices array of strings required

List of 16-character hexadecimal DevEUIs to add to the group.

Examples

Returns

Path Parameters

Body

{
  "devices": [
    "string"
  ]
}

PATCH /v3.2/device_groups/{device_group_id}/add_devices

curl -X PATCH 'https://fuota.machineq.net/api/v3.2/device_groups/{device_group_id}/add_devices'

DeviceVersion

Retrieves the latest reported firmware version for one or more devices.

Endpoints

                GET/v3.2/device_version
GET/v3.2/device_version/all
GET/v3.2/device_version/{deveui}

            

The DeviceVersion object

Attributes

version_hex string

Raw firmware version as a hexadecimal string.

reported_at string (date-time)

Timestamp when the device reported this firmware version, in RFC 3339 format.

firmware_version string

Parsed semantic version derived from version_hex (e.g., "1.2.3").

The DeviceVersion object

{
  "version_hex": "string",
  "reported_at": "2006-01-02T15:04:05.000Z",
  "firmware_version": "string"
}

Retrieves firmware versions for specified devices

Retrieves the reported firmware version for one or more devices identified by deveuis.

Query Parameters

deveuis array of strings required

List of DevEUIs to retrieve firmware versions for. Required. Supports repeated query parameters or a single comma-separated value.

Body Parameters

No parameters.

Returns

Query Parameters

GET /v3.2/device_version

curl 'https://fuota.machineq.net/api/v3.2/device_version'

Retrieves firmware versions for all subscriber devices

Retrieves the firmware version of all devices belonging to the authenticated subscriber. Devices that have never reported a version are excluded from the response.

If delegated_subscriber_id is provided, returns only firmware versions for devices delegated by that subscriber. Returns 404 if the subscriber has no delegated devices.

Query Parameters

delegated_subscriber_id string

Subscriber ID of a delegating subscriber. When provided, returns firmware versions only for devices delegated by this subscriber. Returns 404 if no devices are delegated.

Body Parameters

No parameters.

Returns

Query Parameters

GET /v3.2/device_version/all

curl 'https://fuota.machineq.net/api/v3.2/device_version/all'

Retrieves firmware version for a single device

Retrieves the reported firmware version for a single device identified by deveui. Returns 404 if the device has never reported a version.

Path Parameters

deveui string required

DevEUI of the device to retrieve the firmware version for. 16-character hexadecimal string.

Body Parameters

No parameters.

Returns

Path Parameters

GET /v3.2/device_version/{deveui}

curl 'https://fuota.machineq.net/api/v3.2/device_version/{deveui}'

UpdateHistory

Retrieves device firmware update history records.

Endpoints

                GET/v3.2/history
GET/v3.2/history/{deveui}

The UpdateHistory object

Attributes

entry_date string (date-time)

Timestamp when the history entry was recorded, in RFC 3339 format.

status string

Outcome status of the update attempt (e.g., success, failure, timeout).

reason string

Human-readable explanation of the status.

initial_version string | null

Firmware version of the device before the update. Null if unknown.

post_update_version string | null

Firmware version of the device after the update. Null if the device did not report a new version.

expected_version string

Target firmware version the update was intended to install.

campaign_id string | null

Identifier of the campaign that triggered the update. Null if not associated with a campaign.

The UpdateHistory object

{
  "entry_date": "2006-01-02T15:04:05.000Z",
  "status": "string",
  "reason": "string",
  "initial_version": "string",
  "post_update_version": "string",
  "expected_version": "string",
  "campaign_id": "string"
}

Retrieves update history for all devices

Retrieves the firmware update history for every device belonging to the authenticated subscriber.

Body Parameters

No parameters.

Returns

× 200 Returns the update history for all devices belonging to the subscriber, keyed by DevEUI. application/json

{
  "0102030405060708": [
    {
      "campaign_id": "0b8kLa",
      "entry_date": "2022-02-18 22:34:46",
      "expected_version": "0.0.83.0",
      "initial_version": "0.0.84.0",
      "post_update_version": "0.0.83.0",
      "reason": "",
      "status": "SUCCESS"
    },
    {
      "campaign_id": "0b8kLa",
      "entry_date": "2022-02-19 11:51:46",
      "expected_version": "0.0.83.0",
      "initial_version": "0.0.84.0",
      "post_update_version": "0.0.84.0",
      "reason": "",
      "status": "FAIL"
    }
  ],
  "0102030405060709": [
    {
      "campaign_id": "lq159A",
      "entry_date": "2022-02-18 22:29:13",
      "expected_version": "0.0.83.0",
      "initial_version": "0.0.84.0",
      "post_update_version": "0.0.83.0",
      "reason": "",
      "status": "SUCCESS"
    }
  ]
}

{key} array of objects

GET /v3.2/history

curl 'https://fuota.machineq.net/api/v3.2/history'

Retrieves update history for a single device

Retrieves the firmware update history for a single device identified by deveui.

Path Parameters

deveui string required

16-character hexadecimal DevEUI identifying the device.

Body Parameters

No parameters.

Returns

Path Parameters

GET /v3.2/history/{deveui}

curl 'https://fuota.machineq.net/api/v3.2/history/{deveui}'

FirmwareImages

Handles firmware image uploads, listings, and metadata.

Endpoints

                GET/v3.2/images
POST/v3.2/images
GET/v3.2/images/tags
GET/v3.2/images/tags/{image_name}
PUT/v3.2/images/tags/{image_name}
DELETE/v3.2/images/tags/{image_name}
PATCH/v3.2/images/tags/{image_name}/add
PATCH/v3.2/images/tags/{image_name}/remove
DELETE/v3.2/images/{image_id}

            

The FirmwareImages object

Attributes

name string

Filename of the firmware image.

hash string

Hex-encoded hash of the firmware image contents.

tags array of strings

List of tags associated with the firmware image.

The FirmwareImages object

{
  "name": "string",
  "hash": "string",
  "tags": [
    "string"
  ]
}

Lists all firmware images with metadata

Retrieves all available firmware images with their metadata, including name, hash, and tags, for the subscriber.

Body Parameters

No parameters.

Returns

GET /v3.2/images

curl 'https://fuota.machineq.net/api/v3.2/images'

Uploads a firmware image with tags

Creates a new firmware image by uploading a binary file with optional tags. Allowed extensions: .bin, .hex, .sfb.

Body Parameters

image string (binary) required

Binary firmware image file to upload. Allowed extensions: .bin, .hex, .sfb.

tags array of strings

One or more tags to associate with the uploaded image. Defaults to an empty list if omitted.

Returns

Body (multipart/form-data)

POST /v3.2/images

curl -X POST 'https://fuota.machineq.net/api/v3.2/images'

Lists all tags

Retrieves a sorted list of all unique tags across all firmware images for the subscriber.

Body Parameters

No parameters.

Returns

GET /v3.2/images/tags

curl 'https://fuota.machineq.net/api/v3.2/images/tags'

Lists tags for an image

Retrieves a sorted list of tags associated with the specified firmware image.

Path Parameters

image_name string required

Filename of the firmware image.

Body Parameters

No parameters.

Returns

Path Parameters

GET /v3.2/images/tags/{image_name}

curl 'https://fuota.machineq.net/api/v3.2/images/tags/{image_name}'

Replaces tags for an image

Replaces the entire tag list for the specified firmware image with the provided tags. Returns the updated sorted tag list.

Path Parameters

image_name string required

Filename of the firmware image.

Body Parameters

Body string | array of strings required

Alphanumeric label used to categorize a firmware image.

Returns

Path Parameters

Body

"string"

PUT /v3.2/images/tags/{image_name}

curl -X PUT 'https://fuota.machineq.net/api/v3.2/images/tags/{image_name}'

Deletes all tags from an image

Deletes all tags associated with the specified firmware image.

Path Parameters

image_name string required

Filename of the firmware image.

Body Parameters

No parameters.

Returns

Path Parameters

DELETE /v3.2/images/tags/{image_name}

curl -X DELETE 'https://fuota.machineq.net/api/v3.2/images/tags/{image_name}'

Adds tags to an image

Creates one or more new tag associations on the specified firmware image. Returns the updated sorted tag list.

Path Parameters

image_name string required

Filename of the firmware image.

Body Parameters

Body string | array of strings required

Alphanumeric label used to categorize a firmware image.

Returns

Path Parameters

Body

"string"

PATCH /v3.2/images/tags/{image_name}/add

curl -X PATCH 'https://fuota.machineq.net/api/v3.2/images/tags/{image_name}/add'

Removes tags from an image

Removes one or more tags from the specified firmware image. Tags are not validated, allowing removal of previously valid tags that may no longer pass validation. Returns the updated sorted tag list.

Path Parameters

image_name string required

Filename of the firmware image.

Body Parameters

Body string | array of strings required

Returns

Path Parameters

Body

"string"

PATCH /v3.2/images/tags/{image_name}/remove

curl -X PATCH 'https://fuota.machineq.net/api/v3.2/images/tags/{image_name}/remove'

Deletes a firmware image

Deletes the specified firmware image. Fails with 409 if the image is currently used by any campaign.

Path Parameters

image_id string required

Filename of the firmware image to delete.

Body Parameters

No parameters.

Returns

Path Parameters

DELETE /v3.2/images/{image_id}

curl -X DELETE 'https://fuota.machineq.net/api/v3.2/images/{image_id}'

KeyManagement

Manages device encryption keys used during firmware updates.

Endpoints

                POST/v3.2/key_management
DELETE/v3.2/key_management

Uploads multicast keys for devices

Stores multicast keys to make them available to the FUOTA server when campaigns are created and/or managed by the server. If using MachineQ MQmonitor, MQflex, or MQio devices, there is no need to upload keys.

Body Parameters

Body object required

Mapping of DevEUIs to multicast key values used for firmware update encryption.

Examples

Returns

Body

{
  "string": "string"
}

POST /v3.2/key_management

curl -X POST 'https://fuota.machineq.net/api/v3.2/key_management'

Deletes multicast keys for devices

Deletes multicast keys from the FUOTA server for the provided devices.

Body Parameters

Body array of strings required

List of 16-character hexadecimal DevEUI strings identifying the devices whose multicast keys should be removed.

Returns

Body

[
  "string"
]

DELETE /v3.2/key_management

curl -X DELETE 'https://fuota.machineq.net/api/v3.2/key_management'

ManagedCampaigns

Manages long-running managed campaigns that automatically discover and update devices.

Endpoints

                GET/v3.2/managed_campaigns
POST/v3.2/managed_campaigns
POST/v3.2/managed_campaigns/upload_multicast_keysDeprecated
GET/v3.2/managed_campaigns/{managed_campaign_id}
DELETE/v3.2/managed_campaigns/{managed_campaign_id}
POST/v3.2/managed_campaigns/{managed_campaign_id}/halt
GET/v3.2/managed_campaigns/{managed_campaign_id}/problematic_devices
DELETE/v3.2/managed_campaigns/{managed_campaign_id}/problematic_devices

            

The ManagedCampaigns object

Attributes

name string

Human-readable label for the managed campaign.

include_versions array of strings

List of 16-character hexadecimal version-mask patterns where '.' matches any hex digit. Devices whose firmware version matches any pattern are eligible for update.

exclude_versions array of strings | null

List of 16-character hexadecimal version-mask patterns. Devices whose firmware version matches any pattern are excluded from the campaign. Takes priority over include_versions.

image_name string

Name of a firmware image previously uploaded via the /images endpoint.

expected_version string

16-character hexadecimal version-mask pattern that devices are expected to report after a successful update. If omitted, the server attempts to infer it from semantic versioning in image_name.

preferred_start_time_utc string (time)

UTC time of day (HH:MM) when new child campaigns should be created. Only hours and minutes are used; seconds and below are ignored

stop_when_no_match boolean

When true, the managed campaign transitions to its finished state once no new matching devices are discovered. When false, the campaign continues running until run_until.

run_until string(date-time) | null

RFC 3339 datetime after which no new child campaigns are created. Defaults to seven days from creation when omitted.

gateways array of strings

List of gateway identifiers used to monitor for devices. Currently only a single gateway is supported.

whole_subscriber boolean

Reserved for future use. Must be false; setting to true returns a 400 error.

managed_campaign_id string

Unique identifier assigned to the managed campaign at creation.

next_update_session_time string (date-time)

RFC 3339 datetime of the next scheduled child-campaign creation.

scheduled_devices object

Map of DevEUI to firmware-version information for devices scheduled in the next child campaign.

stage enum (integer)

Managed campaign stages:

INITIALIZING (0): managed campaign was created but the state was not initialized yet
GATHERING_DEVICES (1): the server is gathering a list of devices while waiting for the next start time, and a campaign may or may not be running with previously-discovered devices
RUNNING_LAST_CAMPAIGN (3): no more devices will be gathered, waiting for the last campaign to be launched to finish
FINISHED (7): The last campaign has finished running
CLEANED (8): Finished and all campaigns (7+ days old at this point) have been deleted, this is the final state for a managed campaign
ERROR_SETTING_UP (9): managed campaign failed to set up

The managed campaign is complete when the stage is CLEANED or ERROR_SETTING_UP.

started_at string (date-time)

RFC 3339 datetime when the managed campaign was created.

updated_devices object

Map of DevEUI to firmware-version information for devices that have been successfully updated.

stage_str string

Human-readable name of the current managed campaign stage.

The ManagedCampaigns object

{
  "name": "string",
  "include_versions": [
    "string"
  ],
  "exclude_versions": [
    "string"
  ],
  "image_name": "string",
  "expected_version": "string",
  "preferred_start_time_utc": "string",
  "stop_when_no_match": true,
  "run_until": "2006-01-02T15:04:05.000Z",
  "gateways": [
    "string"
  ],
  "whole_subscriber": true,
  "managed_campaign_id": "string",
  "next_update_session_time": "2006-01-02T15:04:05.000Z",
  "scheduled_devices": {
    "string": {
      "version_hex": "string",
      "reported_at": "2006-01-02T15:04:05.000Z"
    }
  },
  "stage": 0,
  "started_at": "2006-01-02T15:04:05.000Z",
  "updated_devices": {
    "string": {
      "version_hex": "string",
      "reported_at": "2006-01-02T15:04:05.000Z"
    }
  },
  "stage_str": "string"
}

Retrieves all managed campaigns

Retrieves all managed campaigns for the authenticated subscriber.

Body Parameters

No parameters.

Returns

× 200 Returns a list of all managed campaigns belonging to the subscriber. application/json

{
  "expected_version": "04030200........",
  "gateways": [
    "1122334455667788"
  ],
  "image_name": "fuota_v2.3.4.bin",
  "include_versions": [
    "03020100........"
  ],
  "managed_campaign_id": "40TIGg",
  "name": "First managed campaign",
  "next_update_session_time": "2024-08-01T11:12:13.141516Z",
  "preferred_start_time_utc": "11:00",
  "run_until": "2025-01-01T12:00:00.000000Z",
  "scheduled_devices": {
    "1111222233334444": {
      "reported_at": "2024-07-01T01:01:01.010101Z",
      "version_hex": "03020100abcdef00"
    }
  },
  "stage": 1,
  "stage_str": "GATHERING_DEVICES",
  "started_at": "2024-06-06T06:06:06.654321Z",
  "stop_when_no_match": true,
  "updated_devices": {
    "1212232334344545": {
      "reported_at": "2024-06-20T00:00:00.000000Z",
      "version_hex": "04030200abcdef00"
    }
  },
  "whole_subscriber": false
}

{
  "expected_version": "03020100........",
  "gateways": [
    "1122334455667788"
  ],
  "image_name": "fuota_v1.2.3.bin",
  "include_versions": [
    "04030200........"
  ],
  "managed_campaign_id": "RxB15o",
  "name": "Anti-first managed campaign",
  "next_update_session_time": "2024-08-01T11:12:13.141516Z",
  "preferred_start_time_utc": "12:00",
  "run_until": "2025-01-01T12:00:00.000000Z",
  "scheduled_devices": {
    "1111222233334444": {
      "reported_at": "2024-07-02T01:01:01.010101Z",
      "version_hex": "04030200abcdef00"
    }
  },
  "stage": 1,
  "stage_str": "GATHERING_DEVICES",
  "started_at": "2024-06-06T06:06:06.654321Z",
  "stop_when_no_match": true,
  "updated_devices": {
    "1212232334344545": {
      "reported_at": "2024-06-21T00:00:00.000000Z",
      "version_hex": "03020100abcdef00"
    }
  },
  "whole_subscriber": false
}

[
  {
    "expected_version": "04030200........",
    "gateways": [
      "1122334455667788"
    ],
    "image_name": "fuota_v2.3.4.bin",
    "include_versions": [
      "03020100........"
    ],
    "managed_campaign_id": "mWa77N",
    "name": "Some managed campaign",
    "next_update_session_time": "2024-08-01T11:12:13.141516Z",
    "preferred_start_time_utc": "11:00",
    "run_until": "2025-01-01T12:00:00.000000Z",
    "scheduled_devices": {
      "1111222233334444": {
        "reported_at": "2024-07-01T01:01:01.010101Z",
        "version_hex": "03020100abcdef00"
      }
    },
    "stage": 1,
    "stage_str": "GATHERING_DEVICES",
    "started_at": "2024-06-06T06:06:06.654321Z",
    "stop_when_no_match": true,
    "updated_devices": {
      "1212232334344545": {
        "reported_at": "2024-06-20T00:00:00.000000Z",
        "version_hex": "04030200abcdef00"
      }
    },
    "whole_subscriber": false
  }
]

array of objects

List of all managed campaigns belonging to the subscriber.

× Hide array object attributes

name string

Human-readable label for the managed campaign.

include_versions array of strings

List of 16-character hexadecimal version-mask patterns where '.' matches any hex digit. Devices whose firmware version matches any pattern are eligible for update.

exclude_versions array of strings | null

List of 16-character hexadecimal version-mask patterns. Devices whose firmware version matches any pattern are excluded from the campaign. Takes priority over include_versions.

image_name string

Name of a firmware image previously uploaded via the /images endpoint.

expected_version string

16-character hexadecimal version-mask pattern that devices are expected to report after a successful update. If omitted, the server attempts to infer it from semantic versioning in image_name.

preferred_start_time_utc string (time)

UTC time of day (HH:MM) when new child campaigns should be created. Only hours and minutes are used; seconds and below are ignored

stop_when_no_match boolean

When true, the managed campaign transitions to its finished state once no new matching devices are discovered. When false, the campaign continues running until run_until.

run_until string(date-time) | null

RFC 3339 datetime after which no new child campaigns are created. Defaults to seven days from creation when omitted.

gateways array of strings

List of gateway identifiers used to monitor for devices. Currently only a single gateway is supported.

whole_subscriber boolean

Reserved for future use. Must be false; setting to true returns a 400 error.

managed_campaign_id string

Unique identifier assigned to the managed campaign at creation.

next_update_session_time string (date-time)

RFC 3339 datetime of the next scheduled child-campaign creation.

scheduled_devices object

Map of DevEUI to firmware-version information for devices scheduled in the next child campaign.

stage enum (integer)

Managed campaign stages:

INITIALIZING (0): managed campaign was created but the state was not initialized yet
GATHERING_DEVICES (1): the server is gathering a list of devices while waiting for the next start time, and a campaign may or may not be running with previously-discovered devices
RUNNING_LAST_CAMPAIGN (3): no more devices will be gathered, waiting for the last campaign to be launched to finish
FINISHED (7): The last campaign has finished running
CLEANED (8): Finished and all campaigns (7+ days old at this point) have been deleted, this is the final state for a managed campaign
ERROR_SETTING_UP (9): managed campaign failed to set up

The managed campaign is complete when the stage is CLEANED or ERROR_SETTING_UP.

started_at string (date-time)

RFC 3339 datetime when the managed campaign was created.

updated_devices object

Map of DevEUI to firmware-version information for devices that have been successfully updated.

stage_str string

Human-readable name of the current managed campaign stage.

GET /v3.2/managed_campaigns

curl 'https://fuota.machineq.net/api/v3.2/managed_campaigns'

Creates a new managed campaign

Creates a managed campaign that automatically updates devices matching the specified firmware version patterns.

Most parameters have sensible defaults; only include_versions, image_name, and gateways are typically required. The server infers expected_version from the semantic version in image_name when it is not provided. Currently only a single gateway is supported.

include_versions - A list of 16-character hex patterns, where '.' indicates any value. The managed campaign will attempt to load the image onto any device seen by the gateway whose hexadecimal firmware version matches any of the include_versions patterns.
exclude_versions - A list in the same format as include_versions, but with the opposite effect: any device whose firmware version matches any of the exclude_versions patterns.

This takes priority over include_versions, so a device that matched a pattern in both would be excluded from the managed campaign.

Body Parameters

name string

Human-readable label for the managed campaign.

include_versions array of strings required

List of 16-character hexadecimal version-mask patterns where '.' matches any hex digit. Devices whose firmware version matches any pattern are eligible for update.

exclude_versions array of strings | null

List of 16-character hexadecimal version-mask patterns. Devices whose firmware version matches any pattern are excluded from the campaign. Takes priority over include_versions.

image_name string required

Name of a firmware image previously uploaded via the /images endpoint.

expected_version string required

16-character hexadecimal version-mask pattern that devices are expected to report after a successful update. If omitted, the server attempts to infer it from semantic versioning in image_name.

preferred_start_time_utc string (time)

UTC time of day (HH:MM) when new child campaigns should be created. Only hours and minutes are used; seconds and below are ignored

stop_when_no_match boolean

When true, the managed campaign transitions to its finished state once no new matching devices are discovered. When false, the campaign continues running until run_until.

run_until string(date-time) | null

RFC 3339 datetime after which no new child campaigns are created. Defaults to seven days from creation when omitted.

gateways array of strings

List of gateway identifiers used to monitor for devices. Currently only a single gateway is supported.

whole_subscriber boolean

Reserved for future use. Must be false; setting to true returns a 400 error.

Examples

Returns

× 200 Returns the created managed campaign with its assigned identifier and initial state. application/json

{
  "expected_version": "04030200........",
  "gateways": [
    "1122334455667788"
  ],
  "image_name": "fuota_v2.3.4.bin",
  "include_versions": [
    "03020100........"
  ],
  "managed_campaign_id": "mWa77N",
  "name": "Some managed campaign",
  "next_update_session_time": "2024-08-01T11:12:13.141516Z",
  "preferred_start_time_utc": "11:00",
  "run_until": "2025-01-01T12:00:00.000000Z",
  "scheduled_devices": {
    "1111222233334444": {
      "reported_at": "2024-07-01T01:01:01.010101Z",
      "version_hex": "03020100abcdef00"
    }
  },
  "stage": 1,
  "stage_str": "GATHERING_DEVICES",
  "started_at": "2024-06-06T06:06:06.654321Z",
  "stop_when_no_match": true,
  "updated_devices": {
    "1212232334344545": {
      "reported_at": "2024-06-20T00:00:00.000000Z",
      "version_hex": "04030200abcdef00"
    }
  },
  "whole_subscriber": false
}

name string

Human-readable label for the managed campaign.

include_versions array of strings

List of 16-character hexadecimal version-mask patterns where '.' matches any hex digit. Devices whose firmware version matches any pattern are eligible for update.

exclude_versions array of strings | null

List of 16-character hexadecimal version-mask patterns. Devices whose firmware version matches any pattern are excluded from the campaign. Takes priority over include_versions.

image_name string

Name of a firmware image previously uploaded via the /images endpoint.

expected_version string

16-character hexadecimal version-mask pattern that devices are expected to report after a successful update. If omitted, the server attempts to infer it from semantic versioning in image_name.

preferred_start_time_utc string (time)

UTC time of day (HH:MM) when new child campaigns should be created. Only hours and minutes are used; seconds and below are ignored

stop_when_no_match boolean

When true, the managed campaign transitions to its finished state once no new matching devices are discovered. When false, the campaign continues running until run_until.

run_until string(date-time) | null

RFC 3339 datetime after which no new child campaigns are created. Defaults to seven days from creation when omitted.

gateways array of strings

List of gateway identifiers used to monitor for devices. Currently only a single gateway is supported.

whole_subscriber boolean

Reserved for future use. Must be false; setting to true returns a 400 error.

managed_campaign_id string

Unique identifier assigned to the managed campaign at creation.

next_update_session_time string (date-time)

RFC 3339 datetime of the next scheduled child-campaign creation.

scheduled_devices object

Map of DevEUI to firmware-version information for devices scheduled in the next child campaign.

stage enum (integer)

Managed campaign stages:

INITIALIZING (0): managed campaign was created but the state was not initialized yet
GATHERING_DEVICES (1): the server is gathering a list of devices while waiting for the next start time, and a campaign may or may not be running with previously-discovered devices
RUNNING_LAST_CAMPAIGN (3): no more devices will be gathered, waiting for the last campaign to be launched to finish
FINISHED (7): The last campaign has finished running
CLEANED (8): Finished and all campaigns (7+ days old at this point) have been deleted, this is the final state for a managed campaign
ERROR_SETTING_UP (9): managed campaign failed to set up

The managed campaign is complete when the stage is CLEANED or ERROR_SETTING_UP.

started_at string (date-time)

RFC 3339 datetime when the managed campaign was created.

updated_devices object

Map of DevEUI to firmware-version information for devices that have been successfully updated.

stage_str string

Human-readable name of the current managed campaign stage.

Body

{
  "name": "string",
  "include_versions": [
    "string"
  ],
  "exclude_versions": [
    "string"
  ],
  "image_name": "string",
  "expected_version": "string",
  "preferred_start_time_utc": "string",
  "stop_when_no_match": true,
  "run_until": "2006-01-02T15:04:05.000Z",
  "gateways": [
    "string"
  ],
  "whole_subscriber": true
}

POST /v3.2/managed_campaigns

curl -X POST 'https://fuota.machineq.net/api/v3.2/managed_campaigns'

Uploads multicast keys for managed campaigns Deprecated

Stores multicast keys to make them available to managed campaigns. Devices without known keys cannot be included in a managed campaign. Deprecated in favor of /api/latest/key_management.

Body Parameters

Body object required

Mapping of DevEUIs to multicast key values used for firmware update encryption.

Examples

Returns

Body

{
  "string": "string"
}

POST /v3.2/managed_campaigns/upload_multicast_keys

curl -X POST 'https://fuota.machineq.net/api/v3.2/managed_campaigns/upload_multicast_keys'

Retrieves a single managed campaign

Retrieves a managed campaign by managed_campaign_id, including devices that have been updated and devices scheduled for the next child campaign.

Path Parameters

managed_campaign_id string required

Unique identifier of the managed campaign.

Body Parameters

No parameters.

Returns

× 200 Returns the managed campaign details including scheduled and updated devices. application/json

{
  "expected_version": "04030200........",
  "gateways": [
    "1122334455667788"
  ],
  "image_name": "fuota_v2.3.4.bin",
  "include_versions": [
    "03020100........"
  ],
  "managed_campaign_id": "mWa77N",
  "name": "Some managed campaign",
  "next_update_session_time": "2024-08-01T11:12:13.141516Z",
  "preferred_start_time_utc": "11:00",
  "run_until": "2025-01-01T12:00:00.000000Z",
  "scheduled_devices": {
    "1111222233334444": {
      "reported_at": "2024-07-01T01:01:01.010101Z",
      "version_hex": "03020100abcdef00"
    }
  },
  "stage": 1,
  "stage_str": "GATHERING_DEVICES",
  "started_at": "2024-06-06T06:06:06.654321Z",
  "stop_when_no_match": true,
  "updated_devices": {
    "1212232334344545": {
      "reported_at": "2024-06-20T00:00:00.000000Z",
      "version_hex": "04030200abcdef00"
    }
  },
  "whole_subscriber": false
}

name string

Human-readable label for the managed campaign.

include_versions array of strings

List of 16-character hexadecimal version-mask patterns where '.' matches any hex digit. Devices whose firmware version matches any pattern are eligible for update.

exclude_versions array of strings | null

List of 16-character hexadecimal version-mask patterns. Devices whose firmware version matches any pattern are excluded from the campaign. Takes priority over include_versions.

image_name string

Name of a firmware image previously uploaded via the /images endpoint.

expected_version string

16-character hexadecimal version-mask pattern that devices are expected to report after a successful update. If omitted, the server attempts to infer it from semantic versioning in image_name.

preferred_start_time_utc string (time)

UTC time of day (HH:MM) when new child campaigns should be created. Only hours and minutes are used; seconds and below are ignored

stop_when_no_match boolean

When true, the managed campaign transitions to its finished state once no new matching devices are discovered. When false, the campaign continues running until run_until.

run_until string(date-time) | null

RFC 3339 datetime after which no new child campaigns are created. Defaults to seven days from creation when omitted.

gateways array of strings

List of gateway identifiers used to monitor for devices. Currently only a single gateway is supported.

whole_subscriber boolean

Reserved for future use. Must be false; setting to true returns a 400 error.

managed_campaign_id string

Unique identifier assigned to the managed campaign at creation.

next_update_session_time string (date-time)

RFC 3339 datetime of the next scheduled child-campaign creation.

scheduled_devices object

Map of DevEUI to firmware-version information for devices scheduled in the next child campaign.

stage enum (integer)

Managed campaign stages:

INITIALIZING (0): managed campaign was created but the state was not initialized yet
GATHERING_DEVICES (1): the server is gathering a list of devices while waiting for the next start time, and a campaign may or may not be running with previously-discovered devices
RUNNING_LAST_CAMPAIGN (3): no more devices will be gathered, waiting for the last campaign to be launched to finish
FINISHED (7): The last campaign has finished running
CLEANED (8): Finished and all campaigns (7+ days old at this point) have been deleted, this is the final state for a managed campaign
ERROR_SETTING_UP (9): managed campaign failed to set up

The managed campaign is complete when the stage is CLEANED or ERROR_SETTING_UP.

started_at string (date-time)

RFC 3339 datetime when the managed campaign was created.

updated_devices object

Map of DevEUI to firmware-version information for devices that have been successfully updated.

stage_str string

Human-readable name of the current managed campaign stage.

Path Parameters

GET /v3.2/managed_campaigns/{managed_campaign_id}

curl 'https://fuota.machineq.net/api/v3.2/managed_campaigns/{managed_campaign_id}'

Deletes a managed campaign

Deletes a managed campaign identified by managed_campaign_id. The managed campaign must be in the FINISHED, CLEANED, or ERROR_SETTING_UP stage before it can be deleted.

Path Parameters

managed_campaign_id string required

Unique identifier of the managed campaign.

Body Parameters

No parameters.

Returns

Path Parameters

DELETE /v3.2/managed_campaigns/{managed_campaign_id}

curl -X DELETE 'https://fuota.machineq.net/api/v3.2/managed_campaigns/{managed_campaign_id}'

Halts a managed campaign

Halts a managed campaign by managed_campaign_id, stopping any currently-running child campaign. Once halted, the managed campaign transitions into a completed state.

Path Parameters

managed_campaign_id string required

Unique identifier of the managed campaign.

Body Parameters

No parameters.

Returns

Path Parameters

POST /v3.2/managed_campaigns/{managed_campaign_id}/halt

curl -X POST 'https://fuota.machineq.net/api/v3.2/managed_campaigns/{managed_campaign_id}/halt'

Retrieves problematic devices for a managed campaign

Retrieves problematic devices for the managed campaign identified by managed_campaign_id. Problematic devices are those that have failed in two or more child campaigns.

Path Parameters

managed_campaign_id string required

Unique identifier of the managed campaign.

Body Parameters

No parameters.

Returns

Path Parameters

GET /v3.2/managed_campaigns/{managed_campaign_id}/problematic_devices

curl 'https://fuota.machineq.net/api/v3.2/managed_campaigns/{managed_campaign_id}/problematic_devices'

Clears the problematic devices list

Clears the problematic devices list for the managed campaign identified by managed_campaign_id. Future child campaigns will no longer exclude previously problematic devices.

Path Parameters

managed_campaign_id string required

Unique identifier of the managed campaign.

Body Parameters

No parameters.

Returns

Path Parameters

DELETE /v3.2/managed_campaigns/{managed_campaign_id}/problematic_devices

curl -X DELETE 'https://fuota.machineq.net/api/v3.2/managed_campaigns/{managed_campaign_id}/problematic_devices'

ReliableDownlink

Sends reliable downlinks to devices with confirmation and retry logic.

Endpoints

                GET/v3.2/reliable_downlinks
POST/v3.2/reliable_downlinks
GET/v3.2/reliable_downlinks/{job_id}
DELETE/v3.2/reliable_downlinks/{job_id}
PUT/v3.2/reliable_downlinks/{job_id}/restart
PUT/v3.2/reliable_downlinks/{job_id}/stop

            

The ReliableDownlink object

Attributes

name string

Human-readable label for the reliable downlink job.

downlink_hex string

Hexadecimal-encoded payload to send to the devices.

downlink_fport integer

LoRaWAN FPort number for the downlink message.

expected_uplink_hex string

Hexadecimal-encoded payload expected as the device response to the downlink.

expected_uplink_fport integer

LoRaWAN FPort number on which the expected uplink response arrives

devices array of strings | null

Optional list of unique DevEUIs to target. At least one of devices or device_group_id must be provided.

device_group_id string | null

Optional identifier of a device group whose members are targeted. At least one of devices or device_group_id must be provided.

max_retries integer

Maximum number of retry attempts per device before marking it as failed.

retry_interval integer

Delay in seconds between downlink retry attempts per device.

job_id string

Server-assigned unique identifier for the reliable downlink job.

created_at string (date-time)

Timestamp when the job was created, in RFC 3339 format.

successful_devices array of strings | null

List of DevEUIs that responded with the expected uplink. Null when no devices have succeeded yet.

failed_devices array of strings | null

List of DevEUIs that exhausted all retry attempts without the expected response. Null when no devices have failed yet.

device_count integer | null

Total number of devices targeted by the job. Null if the count is unavailable.

successful_count integer | null

Number of devices that responded successfully. Null if the count is unavailable.

failed_count integer | null

Number of devices that failed after all retry attempts. Null if the count is unavailable.

The ReliableDownlink object

{
  "name": "string",
  "downlink_hex": "string",
  "downlink_fport": 0,
  "expected_uplink_hex": "string",
  "expected_uplink_fport": 0,
  "devices": [
    "string"
  ],
  "device_group_id": "string",
  "max_retries": 0,
  "retry_interval": 0,
  "job_id": "string",
  "created_at": "2006-01-02T15:04:05.000Z",
  "successful_devices": [
    "string"
  ],
  "failed_devices": [
    "string"
  ],
  "device_count": 0,
  "successful_count": 0,
  "failed_count": 0
}

Lists all reliable downlink jobs with status

Retrieves all reliable downlink jobs for the authenticated subscriber, including device completion statuses.

Body Parameters

No parameters.

Returns

× 200 List of all jobs with device completion statuses. application/json

[
  {
    "created_at": "2023-10-17T20:29:12.925738Z",
    "devices": [
      "0102030405060708",
      "0102030405060709"
    ],
    "downlink_fport": 73,
    "downlink_hex": "01020304",
    "expected_uplink_fport": 73,
    "expected_uplink_hex": "0101",
    "job_id": "bk64vg",
    "max_retries": 10,
    "name": "Update devices config",
    "retry_interval": 30
  }
]

[
  {
    "created_at": "2023-10-17T20:29:12.925738Z",
    "device_count": 2,
    "devices": [
      "0102030405060708",
      "0102030405060709"
    ],
    "downlink_fport": 73,
    "downlink_hex": "01020304",
    "expected_uplink_fport": 73,
    "expected_uplink_hex": "0101",
    "failed_count": 1,
    "failed_devices": [
      "0102030405060709"
    ],
    "job_id": "ila81a",
    "max_retries": 10,
    "name": "Update devices config",
    "retry_interval": 30,
    "successful_count": 1,
    "successful_devices": [
      "0102030405060708"
    ]
  }
]

array of objects

List of all reliable downlink jobs with their device completion statuses.

× Hide array object attributes

name string

Human-readable label for the reliable downlink job.

downlink_hex string

Hexadecimal-encoded payload to send to the devices.

downlink_fport integer

LoRaWAN FPort number for the downlink message.

expected_uplink_hex string

Hexadecimal-encoded payload expected as the device response to the downlink.

expected_uplink_fport integer

LoRaWAN FPort number on which the expected uplink response arrives

devices array of strings | null

Optional list of unique DevEUIs to target. At least one of devices or device_group_id must be provided.

device_group_id string | null

Optional identifier of a device group whose members are targeted. At least one of devices or device_group_id must be provided.

max_retries integer

Maximum number of retry attempts per device before marking it as failed.

retry_interval integer

Delay in seconds between downlink retry attempts per device.

job_id string

Server-assigned unique identifier for the reliable downlink job.

created_at string (date-time)

Timestamp when the job was created, in RFC 3339 format.

successful_devices array of strings | null

List of DevEUIs that responded with the expected uplink. Null when no devices have succeeded yet.

failed_devices array of strings | null

List of DevEUIs that exhausted all retry attempts without the expected response. Null when no devices have failed yet.

device_count integer | null

Total number of devices targeted by the job. Null if the count is unavailable.

successful_count integer | null

Number of devices that responded successfully. Null if the count is unavailable.

failed_count integer | null

Number of devices that failed after all retry attempts. Null if the count is unavailable.

GET /v3.2/reliable_downlinks

curl 'https://fuota.machineq.net/api/v3.2/reliable_downlinks'

Creates a reliable downlink job

Creates a reliable downlink job that sends the specified payload and waits for an expected device response. Retries automatically at the configured interval until the maximum retry count is reached. Accepts either a list of devices, a device_group_id, or both.

Body Parameters

name string required

Human-readable label for the reliable downlink job.

downlink_hex string required

Hexadecimal-encoded payload to send to the devices.

downlink_fport integer required

LoRaWAN FPort number for the downlink message.

expected_uplink_hex string required

Hexadecimal-encoded payload expected as the device response to the downlink.

expected_uplink_fport integer required

LoRaWAN FPort number on which the expected uplink response arrives

devices array of strings | null

Optional list of unique DevEUIs to target. At least one of devices or device_group_id must be provided.

device_group_id string | null

Optional identifier of a device group whose members are targeted. At least one of devices or device_group_id must be provided.

max_retries integer

Maximum number of retry attempts per device before marking it as failed.

retry_interval integer

Delay in seconds between downlink retry attempts per device.

Examples

Returns

× 200 Newly created reliable downlink job with server-assigned job ID and timestamp. application/json

{
  "created_at": "2023-10-17T20:29:12.925738Z",
  "devices": [
    "0102030405060708",
    "0102030405060709"
  ],
  "downlink_fport": 73,
  "downlink_hex": "01020304",
  "expected_uplink_fport": 73,
  "expected_uplink_hex": "0101",
  "job_id": "bk64vg",
  "max_retries": 10,
  "name": "Update devices config",
  "retry_interval": 30
}

name string

Human-readable label for the reliable downlink job.

downlink_hex string

Hexadecimal-encoded payload to send to the devices.

downlink_fport integer

LoRaWAN FPort number for the downlink message.

expected_uplink_hex string

Hexadecimal-encoded payload expected as the device response to the downlink.

expected_uplink_fport integer

LoRaWAN FPort number on which the expected uplink response arrives

devices array of strings | null

Optional list of unique DevEUIs to target. At least one of devices or device_group_id must be provided.

device_group_id string | null

Optional identifier of a device group whose members are targeted. At least one of devices or device_group_id must be provided.

max_retries integer

Maximum number of retry attempts per device before marking it as failed.

retry_interval integer

Delay in seconds between downlink retry attempts per device.

job_id string

Server-assigned unique identifier for the reliable downlink job.

created_at string (date-time)

Timestamp when the job was created, in RFC 3339 format.

Body

{
  "name": "string",
  "downlink_hex": "string",
  "downlink_fport": 0,
  "expected_uplink_hex": "string",
  "expected_uplink_fport": 0,
  "devices": [
    "string"
  ],
  "device_group_id": "string",
  "max_retries": 0,
  "retry_interval": 0
}

POST /v3.2/reliable_downlinks

curl -X POST 'https://fuota.machineq.net/api/v3.2/reliable_downlinks'

Retrieves a reliable downlink job status

Retrieves the current status of a reliable downlink job identified by job_id, including device success and failure counts.

Path Parameters

job_id string required

Body Parameters

No parameters.

Returns

× 200 Job details with device success and failure counts. application/json

{
  "created_at": "2023-10-17T20:29:12.925738Z",
  "device_count": 2,
  "devices": [
    "0102030405060708",
    "0102030405060709"
  ],
  "downlink_fport": 73,
  "downlink_hex": "01020304",
  "expected_uplink_fport": 73,
  "expected_uplink_hex": "0101",
  "failed_count": 1,
  "failed_devices": [
    "0102030405060709"
  ],
  "job_id": "ila81a",
  "max_retries": 10,
  "name": "Update devices config",
  "retry_interval": 30,
  "successful_count": 1,
  "successful_devices": [
    "0102030405060708"
  ]
}

name string

Human-readable label for the reliable downlink job.

downlink_hex string

Hexadecimal-encoded payload to send to the devices.

downlink_fport integer

LoRaWAN FPort number for the downlink message.

expected_uplink_hex string

Hexadecimal-encoded payload expected as the device response to the downlink.

expected_uplink_fport integer

LoRaWAN FPort number on which the expected uplink response arrives

devices array of strings | null

Optional list of unique DevEUIs to target. At least one of devices or device_group_id must be provided.

device_group_id string | null

Optional identifier of a device group whose members are targeted. At least one of devices or device_group_id must be provided.

max_retries integer

Maximum number of retry attempts per device before marking it as failed.

retry_interval integer

Delay in seconds between downlink retry attempts per device.

job_id string

Server-assigned unique identifier for the reliable downlink job.

created_at string (date-time)

Timestamp when the job was created, in RFC 3339 format.

successful_devices array of strings | null

List of DevEUIs that responded with the expected uplink. Null when no devices have succeeded yet.

failed_devices array of strings | null

List of DevEUIs that exhausted all retry attempts without the expected response. Null when no devices have failed yet.

device_count integer | null

Total number of devices targeted by the job. Null if the count is unavailable.

successful_count integer | null

Number of devices that responded successfully. Null if the count is unavailable.

failed_count integer | null

Number of devices that failed after all retry attempts. Null if the count is unavailable.

Path Parameters

GET /v3.2/reliable_downlinks/{job_id}

curl 'https://fuota.machineq.net/api/v3.2/reliable_downlinks/{job_id}'

Deletes a reliable downlink job

Deletes the reliable downlink job identified by job_id. Stops all pending device downlink attempts, clears queued downlinks, and removes the job and its associated device states.

Path Parameters

job_id string required

Body Parameters

No parameters.

Returns

Path Parameters

DELETE /v3.2/reliable_downlinks/{job_id}

curl -X DELETE 'https://fuota.machineq.net/api/v3.2/reliable_downlinks/{job_id}'

Restarts a reliable downlink job

Restarts the reliable downlink job identified by job_id by re-sending the downlink to all previously failed devices. Fails if any devices are still actively being processed or if all devices already succeeded.

Path Parameters

job_id string required

Body Parameters

No parameters.

Returns

× 200 Restarted job with updated device list targeting previously failed devices. application/json

{
  "created_at": "2023-10-17T20:29:12.925738Z",
  "devices": [
    "0102030405060708",
    "0102030405060709"
  ],
  "downlink_fport": 73,
  "downlink_hex": "01020304",
  "expected_uplink_fport": 73,
  "expected_uplink_hex": "0101",
  "job_id": "bk64vg",
  "max_retries": 10,
  "name": "Update devices config",
  "retry_interval": 30
}

name string

Human-readable label for the reliable downlink job.

downlink_hex string

Hexadecimal-encoded payload to send to the devices.

downlink_fport integer

LoRaWAN FPort number for the downlink message.

expected_uplink_hex string

Hexadecimal-encoded payload expected as the device response to the downlink.

expected_uplink_fport integer

LoRaWAN FPort number on which the expected uplink response arrives

devices array of strings | null

Optional list of unique DevEUIs to target. At least one of devices or device_group_id must be provided.

device_group_id string | null

Optional identifier of a device group whose members are targeted. At least one of devices or device_group_id must be provided.

max_retries integer

Maximum number of retry attempts per device before marking it as failed.

retry_interval integer

Delay in seconds between downlink retry attempts per device.

job_id string

Server-assigned unique identifier for the reliable downlink job.

created_at string (date-time)

Timestamp when the job was created, in RFC 3339 format.

Path Parameters

PUT /v3.2/reliable_downlinks/{job_id}/restart

curl -X PUT 'https://fuota.machineq.net/api/v3.2/reliable_downlinks/{job_id}/restart'

Stops a reliable downlink job

Stops the reliable downlink job identified by job_id. Halts all pending device downlink attempts and transitions pending devices to the failed state. Devices that already succeeded remain successful. Even if a downlink was already queued and delivered, the device response is ignored after stopping.

Path Parameters

job_id string required

Body Parameters

No parameters.

Returns

× 200 Job status after stopping, with pending devices transitioned to failed. application/json

{
  "created_at": "2023-10-17T20:29:12.925738Z",
  "device_count": 2,
  "devices": [
    "0102030405060708",
    "0102030405060709"
  ],
  "downlink_fport": 73,
  "downlink_hex": "01020304",
  "expected_uplink_fport": 73,
  "expected_uplink_hex": "0101",
  "failed_count": 1,
  "failed_devices": [
    "0102030405060709"
  ],
  "job_id": "ila81a",
  "max_retries": 10,
  "name": "Update devices config",
  "retry_interval": 30,
  "successful_count": 1,
  "successful_devices": [
    "0102030405060708"
  ]
}

name string

Human-readable label for the reliable downlink job.

downlink_hex string

Hexadecimal-encoded payload to send to the devices.

downlink_fport integer

LoRaWAN FPort number for the downlink message.

expected_uplink_hex string

Hexadecimal-encoded payload expected as the device response to the downlink.

expected_uplink_fport integer

LoRaWAN FPort number on which the expected uplink response arrives

devices array of strings | null

Optional list of unique DevEUIs to target. At least one of devices or device_group_id must be provided.

device_group_id string | null

Optional identifier of a device group whose members are targeted. At least one of devices or device_group_id must be provided.

max_retries integer

Maximum number of retry attempts per device before marking it as failed.

retry_interval integer

Delay in seconds between downlink retry attempts per device.

job_id string

Server-assigned unique identifier for the reliable downlink job.

created_at string (date-time)

Timestamp when the job was created, in RFC 3339 format.

successful_devices array of strings | null

List of DevEUIs that responded with the expected uplink. Null when no devices have succeeded yet.

failed_devices array of strings | null

List of DevEUIs that exhausted all retry attempts without the expected response. Null when no devices have failed yet.

device_count integer | null

Total number of devices targeted by the job. Null if the count is unavailable.

successful_count integer | null

Number of devices that responded successfully. Null if the count is unavailable.

failed_count integer | null

Number of devices that failed after all retry attempts. Null if the count is unavailable.

Path Parameters

PUT /v3.2/reliable_downlinks/{job_id}/stop

curl -X PUT 'https://fuota.machineq.net/api/v3.2/reliable_downlinks/{job_id}/stop'

UpgradeDelegation

Manages upgrade delegations that allow one subscriber to update another subscriber's devices.

Endpoints

                GET/v3.2/upgrade_delegation
POST/v3.2/upgrade_delegation
GET/v3.2/upgrade_delegation/{delegation_id}
PATCH/v3.2/upgrade_delegation/{delegation_id}
DELETE/v3.2/upgrade_delegation/{delegation_id}

            

The UpgradeDelegation object

Attributes

delegate_to string

Subscriber ID of the party receiving upgrade management permissions.

expires_at string (date-time)

RFC 3339 timestamp indicating when the delegation expires. Requests after this time are rejected.

include_devices array of strings

List of DevEUI patterns identifying devices included in the delegation.

exclude_devices array of strings

List of DevEUI patterns identifying devices excluded from the delegation.

include_gateways array of strings

List of DevEUI patterns identifying gateways included in the delegation. Currently ignored; reserved for future use.

exclude_gateways array of strings

List of DevEUI patterns identifying gateways excluded from the delegation. Currently ignored; reserved for future use.

delegation_id string

Server-assigned unique identifier for the delegation record.

delegate_from string

Subscriber ID of the party that created the delegation.

created_at string (date-time)

RFC 3339 timestamp indicating when the delegation record was created.

The UpgradeDelegation object

{
  "delegate_to": "string",
  "expires_at": "2006-01-02T15:04:05.000Z",
  "include_devices": [
    "string"
  ],
  "exclude_devices": [
    "string"
  ],
  "include_gateways": [
    "string"
  ],
  "exclude_gateways": [
    "string"
  ],
  "delegation_id": "string",
  "delegate_from": "string",
  "created_at": "2006-01-02T15:04:05.000Z"
}

Retrieves all upgrade delegation records

Retrieves all upgrade delegation records for the current subscriber. Includes records where the subscriber is delegating upgrades to another party and records where the subscriber is receiving delegated upgrades.

Body Parameters

No parameters.

Returns

× 200 Returns a list of all delegation records where the current subscriber is either the delegator or the delegatee. application/json

[
  {
    "created_at": "2023-10-17T20:29:12.925738Z",
    "delegate_from": "ujei86",
    "delegate_to": "mq61lp",
    "delegation_id": "qz112p",
    "exclude_devices": [
      "2CC407..00000FF1"
    ],
    "expires_at": "2100-12-31T23:59:59Z",
    "include_devices": [
      "2CC407..00000FF."
    ]
  }
]

array of objects

GET /v3.2/upgrade_delegation

curl 'https://fuota.machineq.net/api/v3.2/upgrade_delegation'

Creates an upgrade delegation record

Creates a new upgrade delegation record that grants another subscriber permission to manage device upgrades.

Check out the documentation about upgrade delegation.

Note: currently the API does not support gateway delegation, only device delegation. The fields include_gateways and exclude_gateways are ignored for now. Later patches will add support for gateway delegation.

Body Parameters

delegate_to string required

Subscriber ID of the party receiving upgrade management permissions.

expires_at string (date-time) required

RFC 3339 timestamp indicating when the delegation expires. Requests after this time are rejected.

include_devices array of strings required

List of DevEUI patterns identifying devices included in the delegation.

exclude_devices array of strings

List of DevEUI patterns identifying devices excluded from the delegation.

include_gateways array of strings

List of DevEUI patterns identifying gateways included in the delegation. Currently ignored; reserved for future use.

exclude_gateways array of strings

List of DevEUI patterns identifying gateways excluded from the delegation. Currently ignored; reserved for future use.

Examples

Returns

× 200 Returns the newly created delegation record with server-assigned delegation_id, delegate_from, and created_at fields. application/json

{
  "created_at": "2023-10-17T20:29:12.925738Z",
  "delegate_from": "ujei86",
  "delegate_to": "mq61lp",
  "delegation_id": "qz112p",
  "exclude_devices": [
    "2CC407..00000FF1"
  ],
  "expires_at": "2100-12-31T23:59:59Z",
  "include_devices": [
    "2CC407..00000FF."
  ]
}

delegate_to string

Subscriber ID of the party receiving upgrade management permissions.

expires_at string (date-time)

RFC 3339 timestamp indicating when the delegation expires. Requests after this time are rejected.

include_devices array of strings

List of DevEUI patterns identifying devices included in the delegation.

exclude_devices array of strings

List of DevEUI patterns identifying devices excluded from the delegation.

include_gateways array of strings

List of DevEUI patterns identifying gateways included in the delegation. Currently ignored; reserved for future use.

exclude_gateways array of strings

List of DevEUI patterns identifying gateways excluded from the delegation. Currently ignored; reserved for future use.

delegation_id string

Server-assigned unique identifier for the delegation record.

delegate_from string

Subscriber ID of the party that created the delegation.

created_at string (date-time)

RFC 3339 timestamp indicating when the delegation record was created.

Body

{
  "delegate_to": "string",
  "expires_at": "string",
  "include_devices": [
    "string"
  ],
  "exclude_devices": [
    "string"
  ],
  "include_gateways": [
    "string"
  ],
  "exclude_gateways": [
    "string"
  ]
}

POST /v3.2/upgrade_delegation

curl -X POST 'https://fuota.machineq.net/api/v3.2/upgrade_delegation'

Retrieves a single upgrade delegation record

Retrieves a single upgrade delegation record by delegation_id. Returns the record regardless of whether the current subscriber is the delegator or the delegatee.

Path Parameters

delegation_id string required

Unique identifier of the delegation record to retrieve.

Body Parameters

No parameters.

Returns

× 200 Returns the delegation record matching the specified delegation_id. application/json

{
  "created_at": "2023-10-17T20:29:12.925738Z",
  "delegate_from": "ujei86",
  "delegate_to": "mq61lp",
  "delegation_id": "qz112p",
  "exclude_devices": [
    "2CC407..00000FF1"
  ],
  "expires_at": "2100-12-31T23:59:59Z",
  "include_devices": [
    "2CC407..00000FF."
  ]
}

delegate_to string

Subscriber ID of the party receiving upgrade management permissions.

expires_at string (date-time)

RFC 3339 timestamp indicating when the delegation expires. Requests after this time are rejected.

include_devices array of strings

List of DevEUI patterns identifying devices included in the delegation.

exclude_devices array of strings

List of DevEUI patterns identifying devices excluded from the delegation.

include_gateways array of strings

List of DevEUI patterns identifying gateways included in the delegation. Currently ignored; reserved for future use.

exclude_gateways array of strings

List of DevEUI patterns identifying gateways excluded from the delegation. Currently ignored; reserved for future use.

delegation_id string

Server-assigned unique identifier for the delegation record.

delegate_from string

Subscriber ID of the party that created the delegation.

created_at string (date-time)

RFC 3339 timestamp indicating when the delegation record was created.

Path Parameters

GET /v3.2/upgrade_delegation/{delegation_id}

curl 'https://fuota.machineq.net/api/v3.2/upgrade_delegation/{delegation_id}'

Updates an upgrade delegation record

Updates an existing upgrade delegation record with a partial patch. Only the subscriber that created the record can update it. Only supplied fields are modified; omitted fields remain unchanged.

Path Parameters

delegation_id string required

Unique identifier of the delegation record to update.

Body Parameters

include_devices array of strings

Replacement list of DevEUI patterns identifying devices included in the delegation.

exclude_devices array of strings

Replacement list of DevEUI patterns identifying devices excluded from the delegation.

expires_at string(date-time) | null

RFC 3339 timestamp indicating the new expiration time. Null leaves the current value unchanged.

include_gateways array of strings

Replacement list of DevEUI patterns identifying gateways included in the delegation. Currently ignored; reserved for future use.

exclude_gateways array of strings

Replacement list of DevEUI patterns identifying gateways excluded from the delegation. Currently ignored; reserved for future use.

Examples

Returns

× 200 Returns the updated delegation record with the patched fields applied. application/json

{
  "created_at": "2023-10-17T20:29:12.925738Z",
  "delegate_from": "ujei86",
  "delegate_to": "mq61lp",
  "delegation_id": "qz112p",
  "exclude_devices": [
    "2CC407..00000FF1"
  ],
  "expires_at": "2100-12-31T23:59:59Z",
  "include_devices": [
    "2CC407..00000FF."
  ]
}

delegate_to string

Subscriber ID of the party receiving upgrade management permissions.

expires_at string (date-time)

RFC 3339 timestamp indicating when the delegation expires. Requests after this time are rejected.

include_devices array of strings

List of DevEUI patterns identifying devices included in the delegation.

exclude_devices array of strings

List of DevEUI patterns identifying devices excluded from the delegation.

include_gateways array of strings

List of DevEUI patterns identifying gateways included in the delegation. Currently ignored; reserved for future use.

exclude_gateways array of strings

List of DevEUI patterns identifying gateways excluded from the delegation. Currently ignored; reserved for future use.

delegation_id string

Server-assigned unique identifier for the delegation record.

delegate_from string

Subscriber ID of the party that created the delegation.

created_at string (date-time)

RFC 3339 timestamp indicating when the delegation record was created.

Path Parameters

Body

{
  "include_devices": [
    "string"
  ],
  "exclude_devices": [
    "string"
  ],
  "expires_at": "2006-01-02T15:04:05.000Z",
  "include_gateways": [
    "string"
  ],
  "exclude_gateways": [
    "string"
  ]
}

PATCH /v3.2/upgrade_delegation/{delegation_id}

curl -X PATCH 'https://fuota.machineq.net/api/v3.2/upgrade_delegation/{delegation_id}'

Deletes an upgrade delegation record

Deletes an upgrade delegation record. Only the subscriber that created the record can delete it.

Path Parameters

delegation_id string required

Unique identifier of the delegation record to delete.

Body Parameters

No parameters.

Returns

Path Parameters

DELETE /v3.2/upgrade_delegation/{delegation_id}

curl -X DELETE 'https://fuota.machineq.net/api/v3.2/upgrade_delegation/{delegation_id}'