Skip to content

API Reference

Jump to bottom
pinjinx edited this page Oct 23, 2026 · 2 revisions

All API endpoints and Server-Sent Events (SSE) streams are served on the host server port (default: 3000). All /api/* paths are handled directly by Rein's embedded HTTP router.

Authentication

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

Authorization: Bearer <token>
GET /api/rtc/session-sse?sessionId=<SESSION_ID>&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 strictly restricted to loopback requests — remote requests return 403 Forbidden.

Host Lifecycle Endpoints

GET /api/host/ip

Returns the server's LAN IP address detected via UDP route inspection.

  • Auth: Token or localhost
  • Response 200: 
    { "ip": "192.168.1.42" }

POST /api/host/start

Starts the GStreamer screen and audio capture engine.

  • Auth: Token or localhost
  • Response 200: 
    { "status": "running" }

POST /api/host/stop

Stops the GStreamer capture process gracefully.

  • Auth: Token or localhost
  • Response 200: 
    { "status": "stopped" }

POST /api/host/restart

Executes a full engine restart: terminates active GStreamer processes, closes active WebRTC client sessions, pauses 200ms to release OS UDP sockets, and re-initializes WebRTCManager and GstManager.

  • Auth: Token or localhost
  • Response 200: 
    { "ok": true, "status": "running" }

GET /api/host/status

Returns the effective status of the GStreamer capture engine and WebRTC manager.

  • Auth: Token or localhost
  • Response 200: 
    { "status": "running" }
  • Possible values: "stopped", "starting", "running", "error"

Authentication Endpoints

POST /api/auth/token

Generates or returns the current active authentication token. Used by the desktop Settings UI to render the pairing QR code.

  • Auth: Localhost only (returns 403 for remote requests)
  • Response 200: 
    { "token": "550e8400-e29b-41d4-a716-446655440000" }

WebRTC Signaling Endpoints (/api/rtc/*)

POST /api/rtc/offer

Initiates a new WebRTC viewer session on the host. Creates the werift RTCPeerConnection, allocates video/audio media tracks and dual data channels (input-unordered, input-ordered), and returns the SDP offer.

  • Auth: Token or localhost
  • Response 200: 
    {
  "sessionId": "b47c9451-872e-450e-b14e-6e87d559869a",
  "offer": {
    "type": "offer",
    "sdp": "v=0\r\no=- 487295729 2 IN IP4 127.0.0.1\r\ns=-\r\n..."
  }
}

POST /api/rtc/answer

Submits the viewer's WebRTC SDP answer to finalize media negotiation.

  • Auth: Token or localhost
  • Request Body: 
    {
  "sessionId": "b47c9451-872e-450e-b14e-6e87d559869a",
  "sdp": {
    "type": "answer",
    "sdp": "v=0\r\no=- ..."
  }
}
  • Response 200: { "ok": true }

POST /api/rtc/ice

Submits a client-gathered ICE candidate to the host peer connection.

  • Auth: Token or localhost
  • Request Body: 
    {
  "sessionId": "b47c9451-872e-450e-b14e-6e87d559869a",
  "candidate": {
    "candidate": "candidate:1 1 UDP 2122252543 192.168.1.150 54123 typ host",
    "sdpMid": "0",
    "sdpMLineIndex": 0
  }
}
  • Response 200: { "ok": true }

GET /api/rtc/session-sse

Subscribes to real-time session events (host ICE candidates and error notifications) via Server-Sent Events.

  • Query Parameters: ?sessionId=<UUID>&token=<TOKEN>
  • Response Header: Content-Type: text/event-stream
  • Events:
    • ice: Host-gathered ICE candidate 
      data: {"type":"ice","candidate":{"candidate":"...","sdpMid":"0","sdpMLineIndex":0}}
    • error: Host runtime error (e.g. driver initialization failure) 
      data: {"type":"error","errorType":"input-injector-init-failed","message":"Linux uinput failure"}

DELETE /api/rtc/session

Closes and cleans up an active WebRTC session, releasing tracks and data channels.

  • Auth: Token or localhost
  • Request Body: 
    { "sessionId": "b47c9451-872e-450e-b14e-6e87d559869a" }
  • Response 200: { "ok": true }

System Clipboard Endpoints (/api/clipboard/*)

POST /api/clipboard/copy

Synthesizes a copy shortcut (Ctrl+C or Cmd+C) on the host, waits 100ms for the OS clipboard buffer to settle, reads plain text via native tools (pbpaste, PowerShell, wl-paste/xclip), and returns the text to the client.

  • Auth: Token or localhost
  • Request Body: { "sessionId": "<active-session-id>" }
  • Response 200: 
    { "ok": true, "text": "Copied text from host" }

POST /api/clipboard/paste

Writes client-provided text to the host system clipboard via child process stdin, then synthesizes a paste shortcut (Ctrl+V or Cmd+V) on the host.

  • Auth: Token or localhost
  • Request Body: 
    {
  "sessionId": "<active-session-id>",
  "text": "Text to paste onto host"
}
  • Response 200: { "ok": true }

File Sharing Endpoints (/api/files/*)

GET /api/files/browse

Lists host directories and files at the specified directory path.

  • Auth: Token or localhost
  • Query Parameter: ?path=<dirPath> (defaults to configured uploadDir)
  • Response 200: 
    {
  "currentPath": "/home/user/Downloads/ReinShared",
  "parentPath": "/home/user/Downloads",
  "items": [
    {
      "name": "documents",
      "path": "/home/user/Downloads/ReinShared/documents",
      "isDir": true,
      "size": 0,
      "mimeType": "directory",
      "modifiedAt": 1720000000000
    },
    {
      "name": "screenshot.png",
      "path": "/home/user/Downloads/ReinShared/screenshot.png",
      "isDir": false,
      "size": 245100,
      "mimeType": "image/png",
      "modifiedAt": 1720000000000
    }
  ]
}

POST /api/files/upload

Uploads a file to the host uploadDir using multipart/form-data. Saves the file to disk and broadcasts an incoming-file event over the files SSE stream.

  • Auth: Token or localhost
  • Payload: multipart/form-data with file field (max 512 MB)
  • Response 200: 
    {
  "ok": true,
  "fileId": "6f1b1c2d-...",
  "path": "/home/user/Downloads/ReinShared/presentation.pdf"
}

GET /api/files/list

Returns metadata for all files in the in-memory shared file store.

  • Auth: Token or localhost
  • Response 200: 
    {
  "files": [
    {
      "id": "6f1b1c2d-...",
      "name": "presentation.pdf",
      "size": 1048576,
      "mimeType": "application/pdf",
      "uploadedAt": 1720000000000,
      "uploadedBy": "host"
    }
  ]
}

GET /api/files/download

Streams file binary data to the caller with appropriate Content-Disposition attachment headers.

  • Auth: Token or localhost
  • Query Parameters: ?path=<filePath> or ?fileId=<id>
  • Response: Binary stream with Content-Type and Content-Disposition: attachment; filename="..."

DELETE /api/files

Deletes a shared file entry from the file store and broadcasts a file-deleted event over SSE.

  • Auth: Token or localhost
  • Query Parameter: ?fileId=<id>
  • Response 200: { "ok": true }

GET /api/files/events

Subscribes to real-time file sharing notifications via Server-Sent Events.

  • Auth: Token or localhost
  • Response Header: Content-Type: text/event-stream
  • Events:
    • incoming-file: Broadcast when a file finishes uploading
    • file-deleted: Broadcast when a file is removed

Configuration Endpoints

GET /api/config

Returns active server pipeline and file configuration.

  • Auth: Token or localhost
  • Response 200: 
    {
  "ok": true,
  "config": {
    "framerate": 60,
    "streamQuality": "performance",
    "frontendPort": 3000,
    "uploadDir": "/home/user/Downloads/ReinShared"
  }
}

POST /api/config

Updates runtime input settings and persisted pipeline configuration.

  • Auth: Token or localhost
  • Request Body: 
    {
  "sensitivity": 1.5,
  "invertScroll": false,
  "framerate": 60,
  "streamQuality": "intermediate",
  "uploadDir": "/custom/path"
}
  • Response 200: { "ok": true }

Debug & Telemetry Endpoints

GET /api/debug/sessions

Returns telemetry snapshots of all active WebRTC sessions.

  • Auth: Token or localhost
  • Response 200: 
    {
  "hostStatus": "running",
  "sessionCount": 1,
  "sessions": [
    {
      "id": "b47c9451-...",
      "state": "connected",
      "createdAt": 1720000000000,
      "sseViewerCount": 1,
      "hasInputConnection": true,
      "bytesRecv": 12048,
      "bytesSent": 450128
    }
  ],
  "inputConnectionCount": 1,
  "latencyMs": 18
}

POST /api/debug/report-latency

Receives client-side round-trip time (RTT) measurements.

  • Auth: Token or localhost
  • Request Body: { "latencyMs": 24 }
  • Response 200: { "ok": true }

GET /api/debug/logs

Subscribes to live server Winston log events via Server-Sent Events. Replays the last 500 log messages on connection.

  • Auth: Token or localhost
  • Response Header: Content-Type: text/event-stream
  • Format: 
    data: {"timestamp":"2026-10-17T12:00:00.000Z","level":"INFO","message":"Session created, offer sent: b47c9451-..."}

WebRTC DataChannel Message Protocol

All input and gamepad events are transmitted as JSON strings over WebRTC DataChannels.

input-unordered Channel (ordered: false, maxRetransmits: 0)

type Payload Fields Purpose
move dx: number, dy: number Relative trackpad cursor movement deltas
scroll dx: number, dy: number Two-finger scroll deltas
zoom delta: number Pinch-to-zoom delta (synthesizes Ctrl + Wheel)
touch contacts: TouchContact[] Raw multi-finger touch contact injection
gamepad-axis axis: "ls"|"rs", ax: number, ay: number Gamepad analog thumbstick coordinates ([-1.0, 1.0])

input-ordered Channel (ordered: true)

type Payload Fields Purpose
click button: "left"|"right"|"middle", press: boolean Mouse button press or release
absoluteClick button: "left"|"right"|"middle", press: boolean, x: number, y: number Touchscreen tap click; x, y are normalized [0, 1] screen ratios
key key: string Named keyboard key event (e.g. "enter", "escape", "space")
text text: string Direct Unicode text string injection
combo keys: string[] Keyboard shortcut combination (e.g. ["control", "alt", "t"])
copy (none) Synthesizes platform copy shortcut (Ctrl+C or Cmd+C)
paste (none) Synthesizes platform paste shortcut (Ctrl+V or Cmd+V)
gamepad button: GamepadButtonId, press: boolean Virtual gamepad button press or release
ping timestamp: number Client RTT latency measurement ping
pong (Server → Client) timestamp: number Echoed ping timestamp for RTT calculation

Gamepad Button IDs

"a", "b", "x", "y", "lb", "rb", "lt", "rt", "start", "select", "dpad-up", "dpad-down", "dpad-left", "dpad-right", "ls", "rs"

Wiki

Guides

API

Clone this wiki locally