Skip to content
logiccloud Orchestrate

Roll back a device to its previous application version

POST
/api/v1/devices/{id}/rollback-version
curl --request POST \
  --url http://localhost:3000/api/v1/devices/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/rollback-version \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "reason": "v2.4.1 crash-looping on the line-3 gateways", "applicationPackageId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'

Re-deploys, in place, the revision (version and parameters) this device ran before its current one, producing a new manifest version (never reusing or decrementing). The deployment id and the Margo deployment id stay the same: no deployment is created and no instance is deleted (the returned deploymentId is the existing one; since FM-1446 it is no longer a new “Rollback to X” deployment). A device that shares its deployment with other devices is split off first; the others stay on their revision, and deploymentId is then the fork. Returns 409 (code ROLLBACK_NO_PREVIOUS_REVISION) when no earlier revision differs, and 409 (code ROLLBACK_NO_REVISION_TARGET) when the device has only history written before revisions existed. This does not abort an in-flight rollout.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string format: uuid

Device UUID

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
reason

Operator-supplied reason, recorded on the audit entry

string
<= 500 characters
Example
v2.4.1 crash-looping on the line-3 gateways
applicationPackageId

Which application to roll back. Rollback is scoped to one application package; on a device running several, omitting this picks the most recently sealed rollbackable one.

string format: uuid

Responses

Section titled “Responses”

200

Section titled “200”

Device rolled back to its previous version

Media typeapplication/json
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
Examplegenerated
{
  "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"
}

403

Section titled “403”

Forbidden — caller lacks required permission

404

Section titled “404”

Device not found

409

Section titled “409”

No earlier revision to roll back to (ROLLBACK_NO_PREVIOUS_REVISION), or only history without revisions (ROLLBACK_NO_REVISION_TARGET)