Skip to content
logiccloud Orchestrate

Roll back a group of devices to their previous application version

POST
/api/v1/devices/rollback-version
curl --request POST \
  --url http://localhost:3000/api/v1/devices/rollback-version \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "deviceSelector": { "matchLabels": { "site": "plant-a" }, "matchExpressions": [ { "key": "line", "operator": "In", "values": [ "line-3" ] } ] }, "reason": "example", "applicationPackageId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'

Re-deploys, in place, the revision (version and parameters) each matching device ran before its current one. Each device follows the rules of the device route: a device of a shared deployment is split off first, and its Margo deployment id is kept. Devices with no earlier revision, or with history written before revisions existed, are reported as skipped rather than failing the batch. This does not abort an in-flight rollout — see the deployment rollback route.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
x-organization-id
string format: uuid

UUID of the organization (tenant) the request acts in. It selects the tenant and grants nothing: the server checks membership or an open tenant switch. Not needed for global operations. A malformed value returns 400. API keys are fixed to their own organization; another organization returns 403. The x-organization-source header grants nothing.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
deviceSelector
required

Label selector choosing which devices to roll back

object
matchLabels

Exact label equality match; all entries must match (AND).

object
Example
{
  "site": "plant-a"
}
matchExpressions
Array<object>
object
key
required

Label key to match on

string
Example
line
operator
required
string
Allowed values: In NotIn Exists DoesNotExist
Example
In
values
Array<string>
Example
[
  "line-3"
]
reason

Operator-supplied reason, recorded on the audit entry

string
<= 500 characters
applicationPackageId

Which application package to roll back on every matching device.

string format: uuid

Responses

Section titled “Responses”

200

Section titled “200”

Rollback evaluated for every matching device

Media typeapplication/json
object
rolledBack
required
Array<object>
object
deviceId
required
string format: uuid
applicationPackageId
required

The application package that was rolled back. A device may run several applications; only this one was touched.

string format: uuid
fromVersion
required

Application version the device was running before this action

string
toVersion
required

Application version the device has been returned to

string
deploymentId
required

FM-1446: the deployment that now carries the previous version: the device’s existing deployment (re-deployed in place) or, for a device that shared its deployment, the fork split off for it

string format: uuid
supersededInstances
required

Always 0 since FM-1446: a rollback re-deploys in place and deletes no instance. Kept so existing clients keep their response shape.

number
edgeDeploymentId
required

FM-1446: the Margo ApplicationDeployment.id the device sees; unchanged by the rollback

string format: uuid
fromRevision
required

FM-1446: the revision the device ran before the rollback

object
id
required
string format: uuid
nullable
revision
required

Monotonic revision number of the deployment

number
nullable
applicationDescriptionId
required
string format: uuid
version
required

Application version string

string
parameterDigest
required

Sha256 of the canonical JSON of the parameter overrides

string
toRevision
required

FM-1446: the earlier revision the deployment now carries

object
id
required
string format: uuid
nullable
revision
required

Monotonic revision number of the deployment

number
nullable
applicationDescriptionId
required
string format: uuid
version
required

Application version string

string
parameterDigest
required

Sha256 of the canonical JSON of the parameter overrides

string
splitFromDeploymentId

FM-1446: the deployment the device was split off first, when it shared one

string format: uuid
skipped
required
Array<object>
object
deviceId
required
string format: uuid
reason
required

Why the device was skipped (for example no earlier version)

string
Examplegenerated
{
  "rolledBack": [
    {
      "deviceId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "applicationPackageId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "fromVersion": "example",
      "toVersion": "example",
      "deploymentId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "supersededInstances": 1,
      "edgeDeploymentId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "fromRevision": {
        "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "revision": 1,
        "applicationDescriptionId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "version": "example",
        "parameterDigest": "example"
      },
      "toRevision": {
        "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "revision": 1,
        "applicationDescriptionId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "version": "example",
        "parameterDigest": "example"
      },
      "splitFromDeploymentId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
    }
  ],
  "skipped": [
    {
      "deviceId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "reason": "example"
    }
  ]
}

400

Section titled “400”

DeviceSelector missing or malformed

403

Section titled “403”

Forbidden — caller lacks required permission

404

Section titled “404”

No devices matched the selector