Skip to main content

​
Introduction

Welcome to the Haptics Docs API! You can use our API to access Haptics SDK endpoints for controlling compatible haptic devices. All API requests must include the header:
unless explicitly specified otherwise.

​
Base URL

All requests are sent to a single production endpoint:

​
Authentication & Security

Access is scoped to your organization. Your Organization ID and Developer Key (Melody Key) are issued to you by Melody — contact support to request them. Device endpoints are called with a short-lived session token, never the Developer Key directly:
  1. Link a device to your organization with POST /device/otp/confirm/v2 (send your Developer Key in the X-Org-Key header). This returns the device’s Device Key.
  2. Create a session token by exchanging your Developer Key at POST /api/sessions/v2.
  3. Call device endpoints with the session token plus the target Device Key:
Requests with a missing or invalid token return 401 Unauthorized.

​
Making Requests

The API supports standard REST semantics:

​
Example request

All responses return JSON that follows the schemas declared in OpenAPI document such as DeviceInfo, HapticPoint, etc.

​
Core API Domains

​
Device Information

  • Inspect device details
  • Query active session state
  • Update device configuration
  • Set communication mode (BLE or WiFi)

​
Haptic Direct Control

  • Send time‑based motion commands
  • Move device to a target position within a defined time
  • Suitable for custom timeline-driven engines

​
Haptic Points Stream (HPS)

  • Stream timestamped motion points
  • Automatic velocity smoothing
  • Ideal for real‑time high‑frequency control

​
Haptic Script Control (Melody Playback)

  • Built for video‑to‑sensation scripting
  • Upload/assign motion scripts
  • Controls: start, stop, pause, seek
  • Server orchestrates timeline playback

​
Haptic Loop Control

  • Define motion min/max range
  • Movement loops automatically
  • Lightweight continuous patterns

​
One‑Time Password (OTP)

  • Secure short‑lived pairing secrets
  • Generate and confirm OTP during device binding

​
Maintenance & Debug

  • Remote maintenance commands
  • Diagnostics and device status inspection
  • Debug or log retrieval if implemented and permitted by device
For full endpoint, schema, and parameter details, jump into the Melody API Reference — each tab includes deeper context, practical examples, and detailed request/response insights.