Updates the recorded state of a single device's progress within a Dispatch operation.

Used to request cancellation for an individual device operation (instead of a larger fleetwide operation) by specifying the sate as CANCELLATION_REQUESTED. Cancellation is not guaranteed and depends the command's exact state.

About Update Device Operation

Each DeviceOperation record represents one device's slice of a larger Operation. As the underlying dispatch command progresses on the device side, the owning service reports the new state back through this endpoint, which then rolls up into the parent operation's aggregate stats (resolved, dispatched, failed, and success counts). Because this directly affects the parent operation's reported outcome, updates here should come from the service that owns the operation's execution rather than from ad hoc calls.

Key Fields / Request Body

operation_type — the operation type this device operation belongs to, for example CONVERGE

state — the new device operation state, for example SUCCESS

service_id — Optional. identifies the internal service reporting the update, for example drift-service

reason — free text explaining the state change

Common Use Cases

An internal service reporting that a device successfully completed its Converge action

Marking a device's operation as failed after the underlying command times out on the device

Best Practices

Only update state from the service that actually owns execution of the underlying command for that device

Always populate reason when reporting a failure so the cause is visible in the operation's activity history

Workflow

Identify the operationsId and deviceId for the device operation being updated

Determine the device's actual outcome from the underlying command or drift check

PUT the new state, service_id, and reason to this endpoint

Confirm the update is reflected in the parent operation's aggregate stats via GET /v0/operations/{operationId}/

{
  "operation_type": "CONVERGE",
  "state": "CANCELLATION_REQUESTED",
  "service_id": "drift-service",
  "reason": "test"
}

{
  "content": {
    "device_operation_activity": [
      {
        "device_operation_state": "CREATED"
      }
    ]
  }
}