Quickstart Guide

This guide takes you from credentials to a moving stroker: authenticate, link a device, and send your first motion command.

1. Get authenticated

All API traffic goes to a single endpoint:

https://api.getmelody.io

Access is scoped to your organization. Your Organization ID and Developer Key are issued by Melody — contact support to request them. Devices are controlled with a short-lived session token, not with the Developer Key itself:

Link a device to your organization via POST /device/otp/confirm/v2 (Developer Key in the X-Org-Key header) to get its Device Key.
Exchange your Developer Key for a session token at POST /api/sessions/v2.
Send every device request with both headers:

Content-Type: application/json
Authorization: Bearer <SESSION_TOKEN>
X-Device-Key: <DEVICE_KEY>

A missing or invalid token returns 401 Unauthorized.

2. Connect your device

Connect the device to WiFi so it can reach the Melody server — the API in this guide talks to the device through the server, so the device has to be online. GET /device/session answers 200 once it is, and 404 while it is not. BLE is a separate, local path: an app next to the device can drive it directly over GATT, without the server and without this API. The position and timing semantics are the same, but the wire format is not — see the BLE Services Reference.

Transport	Description
BLE (Bluetooth Low Energy)	Nearby pairing and low-latency motion commands
WiFi	Network-connected control through the device’s WiFi API

3. Send your first haptic command

POST /device/hdc/command moves the stroker to a target position over a given time.

position — target position, 0 to 10000 (0.01% of the calibrated range per step)
time — how long the move takes, in milliseconds

Example request

curl --request POST \
  --url https://api.getmelody.io/device/hdc/command \
  --header 'Authorization: Bearer <SESSION_TOKEN>' \
  --header 'X-Device-Key: <DEVICE_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "position": 5000,
  "time": 500
}'

This drives the stroker to mid-stroke over half a second.

4. Pick a playback protocol

Direct control is one of four ways to drive the device. Choose the one that matches your source material:

Protocol	What it does	Use it for
HDC — Haptic Direct Control	Move to a target position over a set time	Manual and UI-driven control
HPS — Haptic Points Stream	Stream timestamped points; the device derives velocity from the gaps between them	Real-time or generated motion
HSC — Haptic Script Control	The device loads a script and the server drives start, seek, pause, and stop	Pre-recorded video and VR content
HLC — Haptic Loop Control	Loop between two positions at a set velocity	Continuous repeating motion

HPS needs at least two points before the stroker moves. HSC is available over WiFi only.

5. Next steps

Melody Overview & Setup

Device modes, position and velocity ranges, and how the playback protocols differ across transports.

BLE API Integration

The GATT services and characteristics the device exposes over Bluetooth Low Energy.

WiFi Device Integration

Read device info and status, and send commands over the WiFi API.

API Reference

Every endpoint, schema, and parameter.

Getting started

Melody

Melody Streaming

Melody WiFi

Melody BLE

Quickstart Guide

1. Get authenticated

2. Connect your device

3. Send your first haptic command

Example request

4. Pick a playback protocol

5. Next steps

Melody Overview & Setup

BLE API Integration

WiFi Device Integration

API Reference

​1. Get authenticated

​2. Connect your device

​3. Send your first haptic command

​Example request

​4. Pick a playback protocol

​5. Next steps

Melody Overview & Setup

BLE API Integration

WiFi Device Integration

API Reference

1. Get authenticated

2. Connect your device

3. Send your first haptic command

Example request

4. Pick a playback protocol

5. Next steps