ReflectOS Developer Docs

Quick Start

The SDK runs on-device and communicates with ReflectOS over HTTPS. You trigger a scan from your UI, receive results via callback or webhook.

npm install @reflectos/oem-sdk

const { ReflectOS } = require('@reflectos/oem-sdk');

const mirror = new ReflectOS({
  apiKey: process.env.REFLECTOS_API_KEY,
  deviceId: 'your-mirror-serial',
  region: 'us-east-1' // or 'eu-west-1'
});

mirror.on('scanComplete', (results) => {
  console.log(results.vitals.heartRate); // e.g. 67
});

// User faces the mirror for 30 seconds.
// SDK handles camera capture, processing, and result delivery.

mirror.startScan({ durationMs: 30000 })
  .then(sessionId => console.log('Scan started:', sessionId))
  .catch(err => console.error('Camera unavailable:', err));

Authentication

All API calls use a long-lived API key per device, plus a short-lived session token for scan submissions.

POST https://api.reflectos.ai/v1/devices/provision
Authorization: Bearer {OEM_API_KEY}
Content-Type: application/json

{
  "serial": "MIR-2024-ABC123",
  "model": "X1-Pro",
  "firmwareVersion": "2.4.1"
}

POST https://api.reflectos.ai/v1/auth/session
Authorization: Device {DEVICE_KEY}

→ { "token": "tok_abc123", "expiresAt": "2026-06-12T12:05:00Z" }

Vitals Data Schema

Scan results are returned as a JSON object conforming to the ReflectOS Health Schema (FHIR R4 compatible).

{
  "sessionId": "sess_abc123",
  "timestamp": "2026-06-12T06:45:00Z",
  "duration": 30000,
  "vitals": {
    "heartRate": {
      "value": 67,
      "unit": "bpm",
      "range": { "low": 60, "high": 100 },
      "status": "normal"
    },
    "bloodPressure": {
      "systolic": 118,
      "diastolic": 76,
      "unit": "mmHg",
      "status": "normal"
    },
    "hrv": {
      "value": 54,
      "unit": "ms",
      "range": { "low": 20, "high": 70 },
      "status": "normal"
    },
    "respiratoryRate": {
      "value": 14,
      "unit": "brpm",
      "range": { "low": 12, "high": 20 },
      "status": "normal"
    },
    "stressIndex": {
      "value": 42,
      "unit": "index",
      "range": { "low": 0, "high": 100 },
      "status": "low"   // low | moderate | elevated
    },
    "oxygenSaturation": {
      "value": 98,
      "unit": "%",
      "range": { "low": 95, "high": 100 },
      "status": "normal"
    }
  },
  "scanQuality": {
    "signalStrength": "strong",   // weak | moderate | strong
    "motionDetected": false,
    "confidenceScore": 0.94       // 0–1, exclude readings below 0.7
  }
}

Field definitions

Webhooks

Register a webhook URL in the dashboard or via API to receive real-time scan events. Useful for syncing to your cloud backend or triggering downstream workflows.

Register a webhook

POST https://api.reflectos.ai/v1/webhooks
Authorization: Bearer {OEM_API_KEY}
Content-Type: application/json

{
  "url": "https://your-backend.example.com/reflectos-webhook",
  "events": ["scan.complete", "scan.low_quality", "device.offline"],
  "secret": "wh_secret_abc123"   // sign requests with HMAC-SHA256
}

Event payloads

{
  "event": "scan.complete",
  "deviceId": "dev_abc123",
  "sessionId": "sess_xyz789",
  "timestamp": "2026-06-12T06:45:00Z",
  "vitals": { ... }
}

{
  "event": "scan.low_quality",
  "deviceId": "dev_abc123",
  "sessionId": "sess_xyz789",
  "timestamp": "2026-06-12T06:45:00Z",
  "reason": "motion_detected",
  "retryRecommended": true
}

{
  "event": "device.offline",
  "deviceId": "dev_abc123",
  "lastSeen": "2026-06-10T06:45:00Z"
}

Verifying webhook signatures

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expected}`)
  );
}

Supported Hardware Specs

The SDK supports Android-based smart mirrors. iOS/macOS and bare-metal Linux are on the roadmap.