Skip to main content

Rollback a configuration job

POST 
/v2/configuration-jobs/:id/rollbacks

Rollback a configuration job

Overview​

The Rollback a configuration job endpoint reverses a previously executed configuration job. It does not undo the job in place — instead, it creates one or more new configuration jobs that push the previous configuration back to the affected devices.

Usage​

Use this endpoint when a configuration change caused an incident and you need to restore the previous configuration across the targeted fleet quickly. Typical scenarios:

  • A new CAN profile was rolled out and is misreporting on a subset of devices — roll back to the previous profile.
  • An Operating Mode change put devices into an unintended mode — roll back to the previous mode.

How rollback works​

When you call this endpoint for a given configuration job:

  1. Devices are grouped by the previous configuration they had. Devices that shared the same desired state before the original job are placed in the same group. Each group becomes a single rollback job. This is why one rollback request may return multiple rollback jobs.
  2. Each device is assessed for eligibility before a rollback job is created. Only eligible devices are included.
  3. One rollback job per group is created with type set to ROLLBACK and referenceJobId pointing back to the original job.
  4. Rollback jobs execute immediately like any other configuration job and cannot be modified after creation.

If no targeted device is eligible for rollback, no rollback jobs are created and the endpoint returns 200 OK with an empty items array and a message explaining the outcome.

Eligibility​

A device is eligible for rollback when both of the following are true:

CheckEligible when
Device accessibilityThe account still owns the device.
Configuration unchangedThe current desired state for the affected configuration matches the desired state set by the original job — i.e. nothing has changed the configuration since.

If the configuration has been changed after the original job (manually, by another job, or by automation), the device is not eligible. Rolling it back would silently overwrite that newer intentional change.

Rollback strategy per configuration type​

Rollback is only applied to configurations that have a dedicated rollback strategy. Today, the following configurations support rollback through the public Telematics Device API:

ConfigurationWhen previous configuration existedWhen no previous configuration existed
CAN profileRestore the previous CAN profile.Remove the CAN profile from the device (set profile id 0).
Modbus profileRestore the previous Modbus profile.Remove the Modbus profile from the device (set profile id 0).
Operating ModeRestore the previous operating mode.Set Operating Mode to Normal.

Other configurations the original job may have changed (for example Wi-Fi profiles) are stripped from the rollback's desired state, since there is no rollback strategy for them yet. If a job exclusively touched configurations without a rollback strategy, the resulting rollback jobs may have nothing to apply. Support for additional configurations will be announced in the changelog.

Request​

Path Parameters​

ParameterTypeRequiredDescription
idstring (UUID)YesThe unique identifier of the original configuration job.

Body​

The body is optional. Provide it when you want to control the name of the resulting rollback jobs.

FieldTypeRequiredDescription
namestringNoName applied to the rollback configuration jobs that get created. If omitted, a default of Rollback of configuration job <id> is used.
{
    "name": "Rollback faulty CAN profile rollout"
}

Response​

Success: rollback jobs created​

Status Code: 201 Created

At least one device was eligible. The response lists the rollback jobs that were created. Each item has type set to ROLLBACK and referenceJobId pointing back to the original job. The number of items reflects how many distinct previous configurations were found across eligible devices.

{
    "items": [
        {
            "id": "9f8a3b2c-7e4d-41a2-9b6c-2d1e3f4a5b6c",
            "name": "Rollback faulty CAN profile rollout",
            "type": "ROLLBACK",
            "referenceJobId": "621b4471-059d-47f6-8c2a-91f3be3a4129",
            "deviceIds": [
                "84b6e014-b95c-455a-b990-6cfece467b2a",
                "acd160ee-fcfb-4107-8af2-207bf87b50d3"
            ],
            "desiredStateOnEnter": {
                "desired": {
                    "canbus": {
                        "can1": {
                            "profile": {
                                "id": 129
                            }
                        }
                    }
                }
            },
            "createdAt": "2026-06-01T08:32:11.482137Z"
        },
        {
            "id": "1c2b3a4d-5e6f-47a8-9b0c-1d2e3f4a5b6c",
            "name": "Rollback faulty CAN profile rollout",
            "type": "ROLLBACK",
            "referenceJobId": "621b4471-059d-47f6-8c2a-91f3be3a4129",
            "deviceIds": [
                "7a127747-dbe6-4f8b-8f66-db30a24927e1"
            ],
            "desiredStateOnEnter": {
                "desired": {
                    "canbus": {
                        "can1": {
                            "profile": {
                                "id": 0
                            }
                        }
                    }
                }
            },
            "createdAt": "2026-06-01T08:32:11.488451Z"
        }
    ]
}

Success: no rollback jobs created​

Status Code: 200 OK

The request was accepted, but no devices were eligible for rollback (for example, every device's current configuration has changed since the original job ran, or no devices on the original job remain accessible). No rollback jobs are created.

{
    "items": [],
    "message": "No rollback jobs were created because no devices were eligible for rollback."
}

Error responses​

StatusReason
400The request body is malformed.
401Missing or invalid bearer token.
403The caller does not have permission to manage assets on the account.
404The referenced configuration job does not exist or is not accessible to the caller's account.
500Unexpected server error while creating the rollback jobs.

Tracking the rollback​

Each rollback job in the response is a fully fledged configuration job. Use the regular configuration job tracking endpoints to follow it:

The referenceJobId field on each rollback job links it back to the original job, so you can present the rollback in context of the change it reverses.

Notes​

Why does one rollback call return multiple jobs?

Devices in the original job may have had different configurations before the job ran. To keep each rollback job's payload coherent, devices are grouped by the previous configuration they shared and one rollback job is created per group. Devices that had no previous configuration form their own group; the rollback strategy for that configuration determines what happens to them (for example, removing a CAN profile rather than restoring one).

Why isn't a device included in any rollback job?

A device is excluded when it is no longer accessible to the account, or when its current desired state for the affected configuration differs from the state the original job set — meaning something else has changed the configuration since. Rolling such a device back would silently overwrite that newer change.

Can a rollback job itself be rolled back?

Rollback jobs are configuration jobs of type ROLLBACK. They are intended as terminal corrective actions and cannot be modified or rolled back themselves. To revert further, create a new configuration job with the desired target state.

Request​

Responses​

No rollback jobs were created because no devices were eligible for rollback