API Reference

All endpoints are served on the host server port (default: 3000). All /api/* paths and WebSocket upgrades (/ws) are handled directly by Rein.

---

Authentication

Most endpoints require authentication using a Bearer token in the Authorization header or as a ?token= query parameter:

Authorization: Bearer <token>

GET /ws?token=<TOKEN>

Localhost bypass: Any request originating from loopback IP addresses (127.0.0.1, ::1, ::ffff:127.0.0.1) automatically passes authentication checks.

Localhost-only endpoints: POST /api/auth/token is restricted to localhost requests only — it returns 403 for remote callers.

---

REST & SSE Endpoints

---

GET /api/host/ip

Returns the server's LAN IP address.

Auth: Token or localhost

Response 200:

{ "ip": "192.168.1.42" }

---

POST /api/host/start

Starts the GStreamer screen capture engine.

Auth: Token or localhost

Response 200:

{ "status": "running" }

---

POST /api/host/stop

Stops the GStreamer screen capture engine.

Auth: Token or localhost

Response 200:

{ "status": "stopped" }

---

GET /api/host/status

Returns the current GStreamer capture engine status.

Auth: Token or localhost

Response 200:

{ "status": "running" }

Possible status values: "stopped", "starting", "running", "error"

---

POST /api/auth/token

Generates or returns the active authentication token. Used by the Settings page to generate the connection QR code.

Auth: Localhost only (returns 403 for remote requests)

Response 200:

{ "token": "550e8400-e29b-41d4-a716-446655440000" }

---

POST /api/config

Updates input settings (mouse sensitivity and scroll inversion). Changes are applied immediately to all active connections.

Auth: Token or localhost

Request body:

{
  "sensitivity": 1.5,
  "invertScroll": false,
  "frontendPort": 3000
}

Response 200:

{ "ok": true }

Response 400:

{ "ok": false, "error": "Invalid request body" }

---

GET /api/debug/sessions

Returns snapshots of all active client WebRTC sessions, telemetry metrics, and overall host status for the Debug Dashboard.

Auth: Token or localhost

Response 200:

{
  "hostStatus": "running",
  "sessionCount": 1,
  "sessions": [
    {
      "id": "550e8400-...",
      "state": "connected",
      "createdAt": 1720000000000,
      "sseViewerCount": 1,
      "hasInputConnection": true,
      "bytesRecv": 12048,
      "bytesSent": 450128
    }
  ],
  "inputConnectionCount": 1,
  "latencyMs": 18
}

---

POST /api/debug/report-latency

Receives client-side RTT latency measurements sent periodically from connected trackpad viewers.

Auth: Token or localhost

Request body:

{ "latencyMs": 24 }

Response 200:

{ "ok": true }

---

GET /api/debug/logs

Opens a Server-Sent Events (SSE) stream delivering real-time server log messages to the Debug Dashboard. Replays up to 500 historical log entries on connection.

Auth: Token or localhost

Response: Content-Type: text/event-stream

SSE Data Format:

data: {"timestamp":"2026-07-31T15:00:00.000Z","level":"INFO","message":"Viewer connected via WebSocket: 550e8400-..."}

Sends keepalive comments every 15 seconds: : keep-alive\n\n

---

WebSocket Signaling (/ws)

Real-time WebRTC signaling is conducted over WebSockets at /ws.

URL: ws://<HOST>:<PORT>/ws?token=<TOKEN>

Auth: Valid token in query parameter (or localhost connection)

Server → Client Messages

// WebRTC SDP Offer
{
  "type": "offer",
  "sdp": { "type": "offer", "sdp": "v=0\r\no=- ..." }
}

// Host ICE Candidate
{
  "type": "ice",
  "candidate": { "candidate": "candidate:...", "sdpMid": "0" }
}

// Error Notification
{
  "type": "error",
  "errorType": "Host Error",
  "message": "Capture engine stopped unexpectedly"
}

Client → Server Messages

// WebRTC SDP Answer
{
  "type": "answer",
  "sdp": { "type": "answer", "sdp": "v=0\r\no=- ..." }
}

// Viewer ICE Candidate
{
  "type": "ice",
  "candidate": { "candidate": "candidate:...", "sdpMid": "0" }
}

// WebSocket Ping
{ "type": "ping" }

---

DataChannel Message Protocol

Input events are transmitted as JSON objects over WebRTC DataChannels (input-unordered and input-ordered).

Client → Server Messages

type	DataChannel	Required Fields	Optional Fields	Purpose
move	input-unordered	dx: number, dy: number	—	Relative cursor movement
scroll	input-unordered	dx: number, dy: number	—	Relative scrolling delta
zoom	input-unordered	delta: number	—	Pinch-to-zoom delta
touch	input-unordered	contacts: TouchContact[]	—	Multi-touch contacts
click	input-ordered	button: "left"|"right"|"middle", press: boolean	—	Mouse button click/release
key	input-ordered	key: string	—	Key press event
text	input-ordered	text: string	—	Direct Unicode text string
combo	input-ordered	keys: string[]	—	Key shortcut combination
copy	input-ordered	—	—	Copy shortcut
paste	input-ordered	—	—	Paste shortcut
ping	input-ordered	timestamp: number	—	RTT latency measurement ping

TouchContact Structure

interface TouchContact {
  id: number         // Per-finger tracking identifier
  x: number          // Touch X coordinate
  y: number          // Touch Y coordinate
  state: "down" | "move" | "up"
}

Server → Client Messages

type	DataChannel	Fields	Purpose
pong	input-ordered	timestamp: number	Echoes client ping timestamp for latency calculation