Integration Scenarios

July 03, 2026 06:16

The following scenarios describe where partner integrations can leverage AI-14 power state management. Each scenario shows which API calls and webhooks to use.

Retrieve Stored Recordings from a Parked Vehicle

Scenario: A fleet management platform needs to identify video recordings stored on the device SD card and retrieve specific footage without turning on the camera or triggering a full wake.

Recommendation:

Call GET /devices/{imei}/recording-ranges while the device is in Standby. The cloud automatically wakes the device into Semi-Online mode.
The device returns the available recording ranges while keeping the imagers, screen, and recording functions off.
Call POST /devices/{imei}/connect-media to establish a media connection and stream the required footage from the SD card.
The device remains in Semi-Online mode throughout the operation. Each request resets the inactivity timer.
After the final operation completes and the device remains inactive for 120 seconds, the device automatically returns to Standby.

Create a Virtual Event While the Vehicle Is Parked

Scenario: A partner integration needs to trigger a virtual event on a parked vehicle, such as creating an event marker associated with a specific time or context, without fully waking the device or increasing battery consumption.

Recommendation:

Call POST /devices/{imei}/virtual-event while the device is in Standby.
The cloud automatically wakes the device into Semi-Online mode. The device processes the virtual event while keeping the imagers and screen off.
After 120 seconds of inactivity, the device automatically returns to Standby.

Accurate Fleet-Wide Device Health Monitoring

Scenario: A fleet platform needs to show accurate, real-time device status across the fleet.

Recommendation:

Subscribe to the deviceStatus webhook to receive real-time notifications when device power states change.
Use the status field (Online, Standby, or Offline) together with the isSemiOnline boolean value to identify the current device state.
When multiple webhook events arrive during a state transition, use the changedAt timestamp instead of the webhook arrival order to identify the most recent status.
Implement a short grace period before treating an Offline status as final. This approach helps prevent temporary transition states from being interpreted as a disconnected device.
Use GET /organizations/{orgId}/devices or GET /partner-devices to poll the current fleet status in addition to webhook based updates.

Battery-Conscious Remote Operations for Parked Vehicles

Scenario: A partner needs to perform remote operations on parked vehicles regularly, such as nightly footage retrieval, while minimizing vehicle battery consumption.

Recommendation:

For operations that do not require live recording or Live View, use the Semi-Online supported endpoints (recording-ranges, connect-media, and virtual-event) instead of sending a full Wake request.
Use the explicit Wakeup endpoint (POST /devices/{imei}/wakeup) only for operations that require the device to be fully Online, such as live streaming, Live View, or configuration updates that require full device functionality.
Perform multiple supported operations within a single Semi-Online session whenever possible. Each request resets the inactivity timer, which keeps the device in Semi-Online and prevents the device from returning to Standby between requests.

Pre-Wake a Device Before Deciding on an Operation

Scenario: A partner integration workflow requires the device to be ready to process a remote request, even when the specific operation is not yet known. For example, a user opens a vehicle details page and may choose to retrieve footage, create a virtual event, or take no action.

Recommendation:

Call PUT /devices/{imei}/semi-online to transition the device from Standby to Semi-Online mode proactively.
The device wakes with the imagers and screen turned off and remains ready to process supported operations.
After the user selects an operation, call the appropriate supported endpoint. Because the device is already awake, the operation starts with reduced response latency.
If no operation occurs, the device automatically returns to Standby after 120 seconds of inactivity.

Establishing a Media Connection for Parked Vehicle Media Workflows

Scenario: A partner platform needs to establish a media connection to a parked vehicle to support workflows such as retrieving specific video clips or streaming stored footage without fully waking the device.

Recommendation:

Call POST /devices/{imei}/connect-media while the device is in Standby.
The cloud automatically wakes the device into Semi-Online mode and establishes the media connection.
Continue the media workflow while the device remains in Semi-Online mode with the imagers, screen, and recording functions turned off.
After the final operation is completed and the device remains inactive for 120 seconds, the device automatically returns to Standby.

Triggering Full Wake for Live Operations

Scenario: A partner platform needs to initiate a Live View session, start live video streaming, or apply a configuration update that requires the device to operate with all components fully active.

Recommendation:

Call POST /devices/{imei}/wakeup to trigger a full wake.
Wait for the deviceStatus webhook to confirm that the device transitions to the Online state (newDeviceStatus = 1). During the transition, the device may briefly report an intermediate Offline state.
After the device reaches the Online state, proceed with the required operation, such as live streaming, Live View, or a configuration update.
After the operation completes and the Standby timer expires, the device transitions directly back to Standby. The device does not transition through Semi-Online mode during this process.

Retrieve Stored Recordings from a Parked Vehicle

Call GET /devices/{imei}/recording-ranges while the device is in Standby. The cloud automatically wakes the device into Semi-Online mode.

The device returns the available recording ranges while keeping the imagers, screen, and recording functions off.

Call POST /devices/{imei}/connect-media to establish a media connection and stream the required footage from the SD card.

The device remains in Semi-Online mode throughout the operation. Each request resets the inactivity timer.

After the final operation completes and the device remains inactive for 120 seconds, the device automatically returns to Standby.

Create a Virtual Event While the Vehicle Is Parked

Call POST /devices/{imei}/virtual-event while the device is in Standby.

The cloud automatically wakes the device into Semi-Online mode. The device processes the virtual event while keeping the imagers and screen off.

After 120 seconds of inactivity, the device automatically returns to Standby.

Accurate Fleet-Wide Device Health Monitoring

Subscribe to the deviceStatus webhook to receive real-time notifications when device power states change.

Use the status field (Online, Standby, or Offline) together with the isSemiOnline boolean value to identify the current device state.

When multiple webhook events arrive during a state transition, use the changedAt timestamp instead of the webhook arrival order to identify the most recent status.

Implement a short grace period before treating an Offline status as final. This approach helps prevent temporary transition states from being interpreted as a disconnected device.

Use GET /organizations/{orgId}/devices or GET /partner-devices to poll the current fleet status in addition to webhook based updates.

Battery-Conscious Remote Operations for Parked Vehicles

For operations that do not require live recording or Live View, use the Semi-Online supported endpoints (recording-ranges, connect-media, and virtual-event) instead of sending a full Wake request.

Use the explicit Wakeup endpoint (POST /devices/{imei}/wakeup) only for operations that require the device to be fully Online, such as live streaming, Live View, or configuration updates that require full device functionality.

Perform multiple supported operations within a single Semi-Online session whenever possible. Each request resets the inactivity timer, which keeps the device in Semi-Online and prevents the device from returning to Standby between requests.

Pre-Wake a Device Before Deciding on an Operation

Call PUT /devices/{imei}/semi-online to transition the device from Standby to Semi-Online mode proactively.

The device wakes with the imagers and screen turned off and remains ready to process supported operations.

After the user selects an operation, call the appropriate supported endpoint. Because the device is already awake, the operation starts with reduced response latency.

If no operation occurs, the device automatically returns to Standby after 120 seconds of inactivity.

Establishing a Media Connection for Parked Vehicle Media Workflows

Call POST /devices/{imei}/connect-media while the device is in Standby.

The cloud automatically wakes the device into Semi-Online mode and establishes the media connection.

Continue the media workflow while the device remains in Semi-Online mode with the imagers, screen, and recording functions turned off.

After the final operation is completed and the device remains inactive for 120 seconds, the device automatically returns to Standby.

Triggering Full Wake for Live Operations

Call POST /devices/{imei}/wakeup to trigger a full wake.

Wait for the deviceStatus webhook to confirm that the device transitions to the Online state (newDeviceStatus = 1). During the transition, the device may briefly report an intermediate Offline state.

After the device reaches the Online state, proceed with the required operation, such as live streaming, Live View, or a configuration update.

After the operation completes and the Standby timer expires, the device transitions directly back to Standby. The device does not transition through Semi-Online mode during this process.