Cancels an existing Dispatch operation. User-initiated updates support only the CANCELLED state.

Use this endpoint to request cancellation while the operation is in a cancellable state. Internal states such as FAILURE, TIMEOUT, DISPATCHING, and PROCESSING are managed by Esper services and cannot be set through this public API.

About Update Operation

Cancellation is allowed only when the operation's current state permits a transition to CANCELLED. For operations that have already dispatched work, cancellation is asynchronous and some devices may complete before downstream cancellation is processed.

Key Fields / Request Body

state — the new operation state, CANCELLED

reason — free text explaining the state change

Common Use Cases

Cancelling an operation that was created in error or is no longer needed

Best Practices

Check the operation's current state with GET /v0/operations/{operationId}/ before attempting to cancel it

Always include a reason so the cancellation is auditable alongside the operation's activity history

Workflow

Call GET /v0/operations/{operationId}/ to confirm the operation is still in a cancellable state

PUT state CANCELLED and a reason to this endpoint

Re-check the operation to confirm the update took effect