Skip to content

Update a specific DeviceOperation for a specific Operation
Stable

Request

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

Used to request cancellation for an invidual 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}/

Security
device_apiKey
Path
operationsIdstring, (uuid)required

ID of the Operation

Example:0aae03d2-32b4-4cab-b733-6919b84bb2ac
deviceIdstring, (uuid)required

ID of the Device

Example:550e8400-e29b-41d4-a716-446655440000
Bodyapplication/jsonrequired
statestringrequired

The new state for the device operation. Only CANCELLATION_REQUESTED is supported for user-initiated updates. Cancellation is not guaranteed and depends on the command's current execution state on the device.

Value:"CANCELLATION_REQUESTED"
Example:"CANCELLATION_REQUESTED"
service_idstring
Example:"drift-service"
reasonstring
Example:"test"
operation_typestringdeprecated

Optional; resolved from the database if not provided.

Example:"CONVERGE"
cURL
curl -i -X PUT \
  https://api.esper.io/_mock/openapi/v0/operations/0aae03d2-32b4-4cab-b733-6919b84bb2ac/devices/550e8400-e29b-41d4-a716-446655440000/ \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "operation_type": "CONVERGE",
    "state": "CANCELLATION_REQUESTED",
    "service_id": "drift-service",
    "reason": "test"
  }'

Responses

Device Operation updated successfully

Bodyapplication/json
contentobject(device_DeviceOperationWithStats)
Response
{
  "content": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "operation_id": "cb4ede3c-a5d1-45e3-a9d2-fe83accbce52",
    "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
    "state": "CREATED",
    "reason": "",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "device_operation_activity": [ … ]
  }
}