Asynchronous Commands, Events, and State Convergence

Device, media, recording, and host operations often cannot be completed within a single HTTP request. Reliable clients must distinguish between "whether the command was executed" and "whether the business result is ready."

flowchart LR
    S([Start]) --> P[Pending]
    P --> R[Running]
    R --> O{Reach final state}
    O --> X[Succeeded · Failed · TimedOut · Cancelled]

General States

Common process states include Pending, WaitingDependency, Dispatched, and Running; terminal states include Succeeded, Failed, TimedOut, and Cancelled. The history module may contain spellings such as Queued or Canceled; unknown values should be displayed and reported, and must not cause the entire response deserialization to fail.

Commands and Business Results

Polling

Save the commandId/sessionId/correlationId and query using a backoff of 1, 2, 5, and 10 seconds. Do not POST again after the client's own timeout; first query whether the command, resource, or session already exists.

Dependent commands must save the complete dependency chain. If the upstream fails or times out, the downstream must not pretend to execute successfully.

Runtime WebSocket

First read the protocol information from /api/v2/events/runtime/info, then connect to /api/v2/events/runtime/ws using the sub-protocol akstream-runtime-v1.

Clients must handle at least:

• Initial snapshot;
• Incremental events;
• sequence/eventId sorting, deduplication, and gaps;
• ping/pong;
• Permission expiration and server-side closure;
• REST snapshot calibration after reconnection.

Reconnection can be attempted immediately once, then follow a backoff of 1, 2, 5, and 10 seconds, up to a maximum of 30 seconds. Do not assume that messages are never lost during a disconnection.

Late Results

After a command is formally TimedOut, a device may still return a success result late. The platform retains late result audits but will not reverse-overwrite a terminal state that has already been exposed. Clients should display both the formal state and the late evidence; do not misinterpret this as data corruption, and do not automatically change a timed-out business operation to success.

Third-party notifications

Use the documented outbound Webhook subscription for business notifications. Apply its signature verification, deduplication and retry rules; do not call product-component interfaces.

State Machine Checklist

• Save stable business keys and returned IDs for write operations.
• Deduplicate events by eventId.
• Check final business resources only after reaching a terminal state.
• Use only stable failureCode to control branches; do not match against localized error text.
• Query first upon timeout; determine if the operation can be safely replayed before retrying.
• Use REST for calibration after disconnection.
• Log state transitions and compensations into the audit trail.