Skip to main content
Use these endpoints to inspect the device’s connection to the Melody server over WiFi, and to keep its internal clock aligned with server time. All requests are made against the production API:
Every endpoint here needs a session token and the device key, in these headers:

​
Session Status (Read)

Returns the device’s current server session. A device that is not connected returns 404, so use the status code — not a boolean field — to tell whether the device is online.

​
Server Time

Returns {"epoch_ms": …} — the server clock your timeline should follow, so that scripts and HPS streams carrying large millisecond timestamps agree with the device. One call is enough to be roughly right; to be precise, correct for the network:
  1. Call the endpoint about ten times, noting when you sent each request (sent_at) and when the answer arrived (received_at).
  2. For each call, the round trip is received_at - sent_at, so the server clock at the moment the answer arrived is about epoch_ms + round_trip / 2.
  3. The offset you want is that estimate minus your own clock at the same moment.
  4. Smooth the offsets instead of averaging them: ewma = 0.3 * offset + 0.7 * ewma.
  5. From then on, server_time = your_clock + ewma.
While a device is connected over WebSocket, the server also pushes TIME_SYNC frames, which the device echoes back so the server can measure round-trip latency. See Haptic Frames for the framing and Subscription Flow for how a client handles those frames.

​
Integration Notes

  • Confirm the device is online (GET /device/session returns 200, not 404) before sending timeline-based or streamed commands.
  • Read server time during onboarding and before scripted video or VR playback.
  • GET /device/session carries the same clock as server_time, alongside the connection details.
For endpoint details and request and response schemas, see the Melody API Reference.