JSON Conventions

All service interfaces use JSON. This page documents the shared patterns.

Ports

Port	Interface	Version
10001	HTTP REST + WebSocket (simulation channel)	v3.1 (current)
10020	WebSocket (events channel, read-only)	—
10000	Legacy WebSocket (v3.0 — will be removed in v4.0)	v3.0

HTTP response envelope

Every HTTP response uses the same envelope:

Success (with data):

{ "ok": true, "data": { … } }

Success (no data — mutation-only endpoints):

{ "ok": true }

Error:

{ "ok": false, "error": "reason string" }

Deprecated endpoint:

{ "ok": true, "deprecation_warning": "This route is deprecated. Use …" }

HTTP status codes

Code	Meaning
200	Success
400	Bad request — invalid body, ambiguous selector, missing required field
404	Device, session, or resource not found
405	Method not allowed

WebSocket message format

Messages are JSON objects. The top-level keys are device group names (inverse3, verse_grip, wireless_verse_grip) and an optional session key for session-level commands.

Client → service (command):

{
  "session": { "configure": { … } },
  "inverse3": [
    { "device_id": "049D", "configure": { … }, "commands": { … } }
  ]
}

Service → client (state):

{
  "session_id": 7,
  "inverse3": [
    { "device_id": "049D", "config": { … }, "state": { … }, "status": { … } }
  ]
}

The first message from the service includes config (full snapshot); subsequent messages include only state and status. See WebSocket Protocol for the full workflow.

Content type

All HTTP requests with a body must send Content-Type: application/json. WebSocket messages are always plain-text JSON frames.

Unknown keys

Unknown keys are silently ignored

The service currently ignores unrecognised JSON keys without error. If a command seems to have no effect, check the service logs and verify the field names against the API Reference. This behaviour is planned to change in a future version (unknown keys will trigger a warning event).