Decision Flow: Semi-Online vs Full Wake
The following decision flow helps determine whether the operation uses Semi-Online mode or requires a full Wake.
Figure 2 — Decision Flow: Semi-Online vs. Full Online
Use the following rules to determine whether your operation requires Semi-Online mode or a full device wakeup:
Semi-Online | If the operation uses one of the supported Semi-Online operations (recording-ranges, connect-media, or virtual-event), call the endpoint directly. The cloud automatically performs the Semi-Online wake process. |
Full Wake | If the operation requires live recording, live view, streaming, or full device capability, use the explicit Wakeup endpoint (POST /devices/{imei}/wakeup) |
Primary Workflow: Retrieve Recordings from SD Card
The most common Semi-Online workflow involves checking available recordings on the device and retrieving specific footage from the SD card without enabling the camera or triggering a full Wake.
The following sequence diagram illustrates this workflow:
Figure 3 — Semi-Online API Flow: Retrieve Recordings from SD Card
Handling Device Status
Account for brief transitional states: When processing device status webhooks, account for temporary state transitions where the device may briefly report an Offline status before reporting the correct Standby or Online status. Implement a short delay or confirmation window before treating the Offline status as final.
Use the changedAt timestamp: If multiple webhooks arrive in quick succession, the one with the latest changedAt value reflects the true current state — not the one that arrived last.
Do not retry during transient Offline states: Do not treat a temporary Offline status during a power state transition as an error or trigger a retry loop. Wait for the subsequent webhook that confirms the target state.
Reserve Wakeup for full device operations: Use the explicit Wakeup endpoint only for operations that require the device to be fully Online, such as live streaming, live view, or configuration updates. For all other supported operations, allow Semi-Online mode to manage the wake operation automatically.
Monitor firmware versions: Ensure devices run firmware version 14.3.5 or later to support Semi-Online mode and the isSemiOnline field. Update AI-14 devices to the latest firmware releases as they become available to benefit from ongoing improvements to status reporting reliability.