API Overview - Melody

The Melody API lets your application control a linked Melody Device: read its state, send motion commands, run scripted playback, and manage pairing. Unless an endpoint says otherwise, every request carries:

Content-Type: application/json

Base URL

Environment	Base URL	Description
Production	`https://api.getmelody.io`	Live Melody API

Authentication

Access is scoped to your organization. Your Organization ID and Developer Key are issued by Melody — contact support to request them. Device endpoints are called with a short-lived session token, never with the Developer Key directly:

Link a device to your organization with POST /device/otp/confirm/v2, sending your Developer Key in the X-Org-Key header. The response contains the device’s Device Key.
Create a session token by exchanging your Developer Key at POST /api/sessions/v2. Pass an optional device_keys array to restrict the token to specific devices; omit it and the token covers every device linked to your organization.
Call device endpoints with the session token and the target Device Key:

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

A missing or invalid token returns 401 Unauthorized.

Making Requests

The API uses two methods:

Method	Purpose
GET	Read device, stroker, or session state
POST	Send motion commands, control playback, update settings, upload scripts, generate OTP

Anything that changes device state is a POST, including stopping playback (POST /device/hps/stop) and clearing a mode.

Example request

curl -X GET "https://api.getmelody.io/device/info" \
  -H "Authorization: Bearer <SESSION_TOKEN>" \
  -H "X-Device-Key: <DEVICE_KEY>" \
  -H "Content-Type: application/json"

Responses are JSON and follow the schemas declared in the OpenAPI document, such as DeviceInfo and HapticPoint.

Failure responses

A physical device sits behind these endpoints, so many failures are about the device, not your request:

Code	When
`400`	Malformed body, a missing `X-Device-Key`, an unknown settings field, or a value outside its documented range
`401`	Missing or invalid `Authorization`, or a token of the wrong type
`403`	The session token is not allowed to reach that device
`404`	Device unknown, not linked to your organization, or not currently connected
`408`	The device was reached but did not answer in time
`428`	The device answered and refused the command — the usual failure on playback and motion endpoints
`500`	The device answered with something unexpected, or the server could not build the command

428 deserves attention: it is not a client error to retry blindly. It means the device declined — wrong playback protocol selected, calibration missing, or the device is busy.

Endpoint Groups

Device Information

GET /device/id, /device/info, /device/status, /device/session, /device/server-time Read device identity, capabilities, current status, and the active session. GET and POST /device/settings read and update device configuration; GET and POST /device/mode read and set the communication mode.

Haptic Direct Control (HDC)

POST /device/hdc/command · GET /device/hdc/status Move the stroker to a target position over a given time. Best for manual and UI-driven control.

Haptic Points Stream (HPS)

POST /device/hps/{signal,play,pause,stop,seek,flush,setup} · GET /device/hps/status Stream timestamped motion points. The device derives velocity from the time difference between consecutive points, so at least two points are needed before the stroker moves.

Haptic Script Control (HSC)

POST /device/hsc/{start,seek,stop,pause,upload,setup,chunk} · GET /device/hsc/status Server-orchestrated playback of a motion script. Upload a script (in chunks for larger files), then drive it with start, seek, pause, and stop.

Haptic Loop Control (HLC)

POST /device/hlc/{play,pause,stop} · GET /device/hlc/status Loop the stroker between a minimum and maximum position at a set velocity.

Stroker

GET /device/stroker/status, /device/stroker/calibration · GET/POST /device/stroker/settings Read live stroker position and velocity, inspect calibration bounds, and read or update the user position limits.

One-Time Password (OTP)

POST /device/otp/generate · POST /device/otp/confirm/v2 Generate a short-lived pairing secret and confirm it to link a device to your organization.

Maintenance & Debug

POST /device/maintenance/command · GET /device/screen · GET /device/debug/info · POST /device/debug/logging Trigger service commands such as calibration and OTA, read the device’s current display screen, read diagnostic information, and toggle debug logging.

Full request and response schemas for every endpoint are in the Melody API Reference.

​Base URL

​Authentication

​Making Requests

​Example request

​Failure responses

​Endpoint Groups

​Device Information

​Haptic Direct Control (HDC)

​Haptic Points Stream (HPS)

​Haptic Script Control (HSC)

​Haptic Loop Control (HLC)

​Stroker

​One-Time Password (OTP)

​Maintenance & Debug