API Documentation

Complete reference for the REST and WebSocket APIs.

Base URL

https://local.jmw.nz:41443

All REST endpoints are served over HTTPS. The server binds to 127.0.0.1 only.

REST Endpoints

GET /

Health check. Returns service info and available endpoints.

curl https://local.jmw.nz:41443/

Response

{
  "success": true,
  "service": "HapticWebPlugin",
  "version": "1.0.0",
  "endpoints": {
    "/": "Health check",
    "/waveforms": "List available waveforms",
    "/haptic/{waveform}": "Trigger haptic (POST)",
    "/ws": "WebSocket endpoint"
  }
}

GET /waveforms

List all available haptic waveforms.

curl https://local.jmw.nz:41443/waveforms

Response

{
  "success": true,
  "count": 16,
  "waveforms": [
    "sharp_collision",
    "sharp_state_change",
    "knock",
    ...
  ]
}

POST /haptic/{waveform}

Trigger a specific haptic waveform by name.

curl -X POST https://local.jmw.nz:41443/haptic/knock -d ''

Note: The -d '' is required to send a Content-Length header. Without it, curl will wait indefinitely.

Response

{
  "success": true,
  "waveform": "knock"
}

WebSocket API

wss://local.jmw.nz:41443/ws

Protocol

Send a single byte containing the waveform index (0-15)
No response is sent back
Connection stays open for repeated triggers
Binary message type (Uint8Array)

const ws = new WebSocket('wss://local.jmw.nz:41443/ws');

ws.onopen = () => {
  // Trigger waveform at index 0 (sharp_collision)
  ws.send(new Uint8Array([0]));
};

Available Waveforms

16 waveforms across different categories. Use the index for WebSocket, or the API name for REST.

Index	API Name	Category
0	sharp_collision	Precision enhancers
1	sharp_state_change	Progress indicators
2	knock	Incoming events
3	damp_collision	Precision enhancers
4	mad	Progress indicators
5	ringing	Incoming events
6	subtle_collision	Precision enhancers
7	completed	Progress indicators
8	jingle	Incoming events
9	damp_state_change	Precision enhancers
10	firework	Progress indicators
11	happy_alert	Progress indicators
12	wave	Progress indicators
13	angry_alert	Progress indicators
14	square	Progress indicators