Skip to content
Handyverse documentation

Show interactive endpoint panels inside human guides. This preference is saved for future visits.

The Handy REST API v3 request settings

Open full Swagger UI
API documentation · The Handy REST API v3View Markdown

The Handy REST API v3

The Handy API lets you check a device, control its movement, and keep that movement in time with a video, game, or other content. The best place to begin is with a single device: establish a connection, check what it supports, and make one successful request. You can choose the more elaborate controls once those basics are working.

This guide takes you through that process. You can read it from the beginning or use the protocol sections when you know what you want to build. The agent reference supplies the complete endpoint index and exact request requirements when you need more detail.

All examples use the production API:

https://www.handyfeeling.com/api/handy-rest/v3

For exact request and response schemas, use the OpenAPI specification. See API version and reference for version details.

For browser or worker implementations, the small JavaScript request helper shows device addressing, response parsing and error handling.

Contents

Request settings

Open Settings in the page header to choose the API server and enter an Application ID or client token and your device connection key. These values fill the applicable Bash examples and inline requests below. Device keys prefill each applicable panel; you can override a key for an individual request. Values stay in this page and are cleared when you reload it. Keep Authentication Keys on your server.

Use Copy on a Bash example to copy the displayed command, including any configured values. Replace any remaining placeholders before running it. Token-issuance examples retain the server-side Authentication Key placeholder.

Inline Swagger examples are enabled by default. If you prefer the full Swagger UI, turn them off in Settings; that preference is saved for future visits. Curl examples and operation links remain available.

Make your first request

Before you begin, you need an account, an API credential, and your device's connection key. Each has a distinct purpose: the account owns your credentials, the credential identifies your application, and the connection key tells the server which device to reach.

Create an account through the registration page, then use the user portal to create an Application ID. We will use that for the first requests; other credential options are explained below.

Each curl block is self-contained. Replace its inline credential and connection-key placeholders with your own values, then run it. Start by asking whether your device is connected:

You can use curl, open the linked Swagger UI operation, or use the inline panel in the web guide. Panels start collapsed. Open a panel, select Try it out, check the device key and request values, then select Execute. Each panel keeps its own response; opening a panel sends no device command.

Open GET /connected in Swagger UI

curl --silent --show-error --fail-with-body \
  --header 'X-Api-Key: REPLACE_WITH_APPLICATION_ID' \
  --header 'X-Connection-Key: REPLACE_WITH_DEVICE_CONNECTION_KEY' \
  'https://www.handyfeeling.com/api/handy-rest/v3/connected'

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

A connected device can return:

{"result":{"connected":true}}

If connected is false, check the following before continuing:

  • Is the device powered on?
  • Is it connected to Wi-Fi, and does that network have internet access?
  • Does X-Connection-Key contain the connection key for the device you intend to use?

If the device has just started or reconnected, allow time for it to connect to the server, then repeat the request.

If you receive an error object, handle it before continuing. Check the body even when the HTTP status is 200: a device error can arrive in an otherwise successful HTTP response.

Next, ask about the firmware:

Open GET /info in Swagger UI

curl --silent --show-error --fail-with-body \
  --header 'X-Api-Key: REPLACE_WITH_APPLICATION_ID' \
  --header 'X-Connection-Key: REPLACE_WITH_DEVICE_CONNECTION_KEY' \
  'https://www.handyfeeling.com/api/handy-rest/v3/info'

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use fw_version and fw_status to make the compatibility check. Once the firmware is suitable, find out what hardware is available:

Open GET /capabilities in Swagger UI

curl --silent --show-error --fail-with-body \
  --header 'X-Api-Key: REPLACE_WITH_APPLICATION_ID' \
  --header 'X-Connection-Key: REPLACE_WITH_DEVICE_CONNECTION_KEY' \
  'https://www.handyfeeling.com/api/handy-rest/v3/capabilities'

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

These three requests give you a useful starting picture: the device is reachable, its firmware is suitable for your application, and you know which hardware you can use.

Understand the credentials

Start with Developer access to create your account and obtain portal-issued credentials.

For an initial experiment, an Application ID is sufficient. As your application develops, choose the credential that fits where your code runs and what it needs to do.

Credential Where to use it Header What it allows
Application ID (application_id) Browser, mobile application, or server X-Api-Key: APPLICATION_ID Device API operations. It may be visible in client code; its requests still count toward your account's usage.
Authentication Key (authentication_key) Your server Authorization: Bearer AUTHENTICATION_KEY Administrative operations only, such as issuing client tokens. Device endpoints do not accept it. Keep it out of browser and mobile client code.
Client token A client that needs temporary access Authorization: Bearer CLIENT_TOKEN Device API operations, with an expiry and optional restrictions.

Use X-Api-Key for an Application ID. Authentication Keys and client tokens are bearer credentials and use Authorization. For example, a device request using a client token includes:

Authorization: Bearer REPLACE_WITH_CLIENT_TOKEN
X-Connection-Key: REPLACE_WITH_DEVICE_CONNECTION_KEY

Keep supplying the connection key even if the token is bound to that device. The token authorizes the request; the connection key addresses it.

The account access token received during registration is used to manage your account. For device API requests, use an Application ID or a client token. Authentication Keys are accepted only by administrative endpoints, even when your device requests originate on a server. This separation helps keep Authentication Keys out of client code.

Issue a client token

Your server can issue a token with GET /auth/token/issue, using its Authentication Key. Here is a request for one hour of access to a particular device:

Open GET /auth/token/issue in Swagger UI

curl --silent --show-error --fail-with-body --get \
  --header 'Authorization: Bearer REPLACE_WITH_SERVER_SIDE_AUTHENTICATION_KEY' \
  --data-urlencode 'ttl=3600' \
  --data-urlencode 'to=REPLACE_WITH_DEVICE_CONNECTION_KEY' \
  'https://www.handyfeeling.com/api/handy-rest/v3/auth/token/issue'

Both query parameters are optional. ttl is the lifetime in seconds: it defaults to 3600 (1 hour), with a minimum of 60 (1 minute) and a maximum of 86400 (24 hours). to binds the token's use to a specific device connection key. You can also restrict a token by IP address or client headers; see the exact parameters. Choose restrictions that the intended client can satisfy.

Together, the device connection key, IP address, and selected client headers form a lightweight client fingerprint. These optional restrictions narrow the token's use to the intended device and client environment. Requests made with the token must satisfy the restrictions configured when it was issued.

The response includes the token, its expiry, and a renew URL. Use that URL before expiry to extend the token's lifetime with its original restrictions. Once the token expires, its renewal URL expires too. Your server must then issue a new token.

Check expiry when restoring a cached session. If the token has expired, request a replacement through your application's server or token proxy using its saved issuance configuration. An old renew URL cannot recover an expired session. The Authentication Key stays on your server.

Check firmware and hardware

Device control requires firmware v4 or later. There are two compatibility questions to answer: does the server require an update, and does the installed firmware support your application?

GET /info returns the server's assessment in fw_status:

Value What it means for your application
0 — UP_TO_DATE The server considers the firmware up to date. Check that it also meets your application's requirements.
1 — UPDATE_AVAILABLE A newer version exists. Your application decides whether the installed version is supported.
2 — UPDATE_REQUIRED A critical fix is required. Stop device interaction and direct the user to the firmware updater.

A required update takes precedence over your own compatibility policy. Even if the device appears to support your features, status 2 means third-party services should stop interacting with it and direct the user to update.

For status 1, you have a choice. Requiring the latest firmware is simple to maintain. Allowing versions that already support your features avoids asking users to update unnecessarily. A version-aware policy can compare fw_version with the firmware and features your service supports, requiring an update when a needed fix or feature is missing. Apply your own compatibility checks to status 0 as well.

Older firmware has three exceptions: GET /connected, GET /info, and GET /sse. SSE requires firmware v3 or later and provides connection and status events on those devices. Authentication is still required. Other device operations on unsupported firmware return DeviceNotConnected. These exceptions do not permit continued interaction after an UPDATE_REQUIRED result.

Once the firmware check passes, use GET /capabilities to inspect sliders, LRA and ERM motors, battery, and other hardware. The shared Device and protocol compatibility page explains protocol availability, movement output and HRPP file types, with a hardware ID/name reference.

Those values describe physical hardware. Oh has no slider, but it can use slider protocols: the device translates movement commands into vibration. A slider count of 0 therefore does not exclude Oh from HAMP, HDSP, HSP, HSSP or STREAM. Choose HVP when you want to control amplitude and frequency directly.

Keep physical configuration separate from that translation. Request GET /settings/slider only for a device with a physical slider; Oh does not provide those settings. Its translated movement and virtual GET /slider/stroke limits do not depend on that request succeeding.

Notice session changes

GET /sids helps you recognize when the device has rebooted, reconnected, or changed modes. Successful responses always contain three integers:

Field What changes it
boot_session_id A random ID is assigned on each boot.
socket_session_id Starts at zero and increments on each server connection; resets on boot.
mode_session_id Starts at zero and increments on each mode change; resets on boot.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Read mode and traffic diagnostics

GET /mode reports the selected device mode and may include mode_session_id. Compare that ID with /sids within a stable session. The selected mode alone does not establish whether a movement protocol's controls work or whether movement is playing.

Physical buttons are interpreted by that reported mode. See Physical buttons and device modes for mode values and button behavior.

Prefer PUT /mode2 to select a mode, using a body such as {"mode":7} for idle. It returns a mode object and may include mode_session_id. The older PUT /mode is deprecated and returns {"result":"ok"} instead.

Returning to a previous mode does not rewind its session counter. Do not rely on a mode change to preserve earlier buffers or playback state.

GET /statistics reports message traffic. Its timestamp is an object containing Unix epoch seconds and fractional nanos; Unix milliseconds are seconds * 1000 + nanos / 1000000. Message counters are named total_msgs, dropped_msgs, and acked_msgs, alongside the byte and buffer/transit counters. These fields are optional. Retain the session context when comparing readings; do not assume counters continue across sessions. Use the playback clock-synchronization workflow for media timing.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Read the active protocol state

First call GET /mode, then ask for the state belonging to that mode. For example, mode 0 uses GET /hamp/state, while mode 8 uses GET /hvp/state. Protocol entry commands and state queries can select their mode; parameter setters do not necessarily do so. Asking for another protocol's state can therefore switch modes and interrupt playback. Avoid polling every protocol to discover which one is playing.

HSP, HSSP and STREAM need their matching setup step before other protocol commands. That includes Stop and state queries: they require an initialized session too. Once your session is set up, use that workflow's state endpoint. Setup replaces session state and buffered data, so it is a preparation step rather than a way to inspect existing playback.

Both HSP and HSSP report mode 4 (HSP). The mode alone cannot tell you which workflow prepared the session. If you set up HSSP, keep using GET /hssp/state and the HSSP controls; seeing mode 4 is expected.

The initial SSE connection reports connection status and device information. Use the mode-first flow above to populate the current mode and state, then follow subsequent events.

Connect before preparing playback

A Connect button can check whether the device is online, read its firmware information and, once compatible, inspect its capabilities. Connecting does not prepare a playback session. In particular, sending an HSP, HSSP or STREAM Stop before that protocol's setup fails; Stop is not an initialization step.

For a new session, use this order:

  1. Check connection, firmware and capabilities.
  2. Choose your protocol and provide its input: HSP points, an HSSP script URL or a STREAM reference.
  3. Complete that protocol's setup and check the response.
  4. Send Play when your application needs movement to begin.
  5. Use the same protocol's controls, including Stop and state queries, for that prepared session.

For media synchronization, keeping the device stopped while the media is paused is a sensible default. The app designer and user can choose other behavior, including independent device playback. The API does not require device playback to follow the media's play/pause state.

Remember which session your application prepared. Reopening a page or restoring credentials does not establish that the previous session is still available. Use the known mode/session when inspecting existing playback; prepare a new session when your application needs to replace it.

Choose a protocol

Begin with how your application produces movement. A speed control, a prepared video script, and a game generating movements as it runs need different approaches.

Your application needs to… Start with Who supplies the movement?
Move a slider repeatedly at an adjustable speed HAMP (Handy Alternate Motion Protocol) You set speed and stroke.
Control vibration HVP (Handy Vibration Protocol) You set vibration parameters for supported hardware.
React immediately to individual actions HDSP (Handy Direct Streaming Protocol) You send each target with a velocity or duration.
Play a prepared script alongside media STREAM (Handy Stream Protocol) Store the script through the Stream API, then reuse its returned stream_ref for playback.
Keep the familiar v2-style URL-based script setup HSSP (Handy Synchronized Script Protocol) The server fetches the script URL and tries to reuse cached script data.
Generate movements as it runs, for direct play or media synchronization HSP (Handy Streaming Protocol) You add points and manage the device's buffer.
Play live data without managing the device buffer STREAM A separate Stream API supplies data; the server delivers it.
Play patterns already on the device HRPP (Handy Repeating Pattern Protocol) You select an available pattern slot.

HSSP, HSP, and STREAM use a shared server-clock reference to coordinate playback. HDSP forwards individual commands as they arrive. If your immediate goal is to make a slider move and adjust its speed, HAMP is a useful first step.

Start with simple slider movement

HAMP produces repeated motion, with controls similar to the device's speed and stroke buttons. A Handy moves its slider; Oh translates those commands into vibration.

PUT /hamp/start is HAMP's setup command: it enters HAMP mode 0 and starts movement. Reading GET /hamp/state also enters HAMP mode. Enter HAMP before sending its parameter setters; PUT /hamp/stroke alone does not switch an idle device into HAMP.

After checking device and firmware support, set a stroke range, start HAMP, choose a speed, and stop when finished. This example uses a global stroke range of [0.1,0.9] and a velocity setting of 0.2, selecting 20% of the way from the device's configured minimum speed to its maximum. Run each command separately and inspect its response before continuing.

Start deliberately resets the velocity setting to 0 for safety, so movement begins at the low end of the configured speed range instead of reusing a previous higher speed. Zero still produces movement. Apply your chosen velocity after each successful Start; a speed sent before Start will be replaced.

Open PUT /slider/stroke in Swagger UI

curl --silent --show-error --fail-with-body --request PUT \
  --header 'X-Api-Key: REPLACE_WITH_APPLICATION_ID' \
  --header 'X-Connection-Key: REPLACE_WITH_DEVICE_CONNECTION_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"min":0.1,"max":0.9}' 'https://www.handyfeeling.com/api/handy-rest/v3/slider/stroke'

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Open PUT /hamp/start in Swagger UI

curl --silent --show-error --fail-with-body --request PUT \
  --header 'X-Api-Key: REPLACE_WITH_APPLICATION_ID' \
  --header 'X-Connection-Key: REPLACE_WITH_DEVICE_CONNECTION_KEY' \
  'https://www.handyfeeling.com/api/handy-rest/v3/hamp/start'

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Open PUT /hamp/velocity in Swagger UI

curl --silent --show-error --fail-with-body --request PUT \
  --header 'X-Api-Key: REPLACE_WITH_APPLICATION_ID' \
  --header 'X-Connection-Key: REPLACE_WITH_DEVICE_CONNECTION_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"velocity":0.2}' 'https://www.handyfeeling.com/api/handy-rest/v3/hamp/velocity'

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

You can also update velocity and the HAMP-specific stroke together with PUT /hamp/state. This selects the same speed setting and sets the HAMP stroke to [0.1,1] within the global range:

Open PUT /hamp/state in Swagger UI

curl --silent --show-error --fail-with-body --request PUT \
  --header 'X-Api-Key: REPLACE_WITH_APPLICATION_ID' \
  --header 'X-Connection-Key: REPLACE_WITH_DEVICE_CONNECTION_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"velocity":0.2,"stroke":{"min":0.1,"max":1.0}}' 'https://www.handyfeeling.com/api/handy-rest/v3/hamp/state'

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Open PUT /hamp/stop in Swagger UI

curl --silent --show-error --fail-with-body --request PUT \
  --header 'X-Api-Key: REPLACE_WITH_APPLICATION_ID' \
  --header 'X-Connection-Key: REPLACE_WITH_DEVICE_CONNECTION_KEY' \
  'https://www.handyfeeling.com/api/handy-rest/v3/hamp/stop'

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Both the setter and reported state use the 0–1 scale; the nominal speed is x_min_speed + velocity * (x_max_speed - x_min_speed), using the limits from GET /settings/slider. For limits of 32–400 mm/s, a setting of 0.5 selects 216 mm/s. Actual readings vary during oscillation.

Setting velocity to 0 keeps HAMP moving. Use PUT /hamp/stop to stop, and check play_state=0 in GET /hamp/state. You can observe position and speed through GET /slider/state, or HAMP state through hamp_state_changed events. HAMP state may also include optional min and max fields for the HAMP-specific stroke.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Understand the two stroke ranges

PUT /slider/stroke sets the global range used by relative positions across device modes. PUT /hamp/stroke sets a HAMP range within that global range. Both require numeric min and max from 0 through 1, inclusive; fractional values such as 0.1 are valid.

If you want to set HAMP's own range before starting, first call GET /hamp/state to enter HAMP and inspect its state. Then set PUT /hamp/stroke, start with PUT /hamp/start, and apply the chosen velocity. This adjusts the HAMP range while keeping the global limits. The initial state request changes mode, so use it deliberately when entering HAMP rather than to observe another protocol's playback.

For example, a global range of [0.1,0.9] and a HAMP range of [0.1,1] produce an effective range of [0.18,0.9]. To convert a local position into the global range, use:

effective_position = global_min + local_position * (global_max - global_min)

Global stroke replies include relative min/max and absolute min_absolute/max_absolute in millimeters. The position from GET /slider/state uses that global range; position_absolute reports millimeters. Changing the range can therefore change the relative reading without moving the slider. Send both limits when updating the global stroke.

The x_stroke_min and x_stroke_max fields in GET /settings/slider are normalized global endpoints, matching min and max from GET /slider/stroke. They are not minimum or maximum movement lengths in millimeters. To calculate a local HAMP span in millimeters, use (max_absolute - min_absolute) * (local_max - local_min), with the absolute endpoints from GET /slider/stroke and local fractions from 0 to 1. Do not compare that span against x_stroke_min or x_stroke_max as length constraints.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Control vibration

With HVP, start using PUT /hvp/start, adjust vibration through PUT /hvp/state, and stop with PUT /hvp/stop. Starting sets amplitude to its default of 0.3 (30%), replacing the previous amplitude, while preserving the current frequency. Inspect the returned state, then set your desired values. Read the current state with GET /hvp/state.

Use the compatibility matrix to check HVP availability for your model. A slider capability alone does not establish HVP support. An unsupported operation can return an error object inside HTTP 200; inspect the response before continuing.

Amplitude is a number from 0 to 1. Frequency is an integer from 0 to 10000 Hz. The fields you must send depend on the device:

Device Required fields in PUT /hvp/state
Handy Pro variants (H02_pro, H02_1_pro) amplitude, frequency, and position.
Oh vibrator amplitude and frequency; position is not required.

On supported slider devices, position sets the relative point along the slider where oscillation occurs. Use a floating-point value from 0 through 1, inclusive, representing 0–100%; for example, 0.5 selects the midpoint. It is mandatory for Handy 2 Pro; supply it explicitly and do not assume a default. Choose the fields for the hardware you are controlling. The agent reference explains how these device-dependent requirements are represented in the specification.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Send individual movements

HDSP is useful when a game or other application decides on the next movement as events happen. Send a target position together with a velocity or a duration. Commands are forwarded immediately on a best-effort basis, without buffering or built-in synchronization.

Your client is responsible for any synchronization. Allow for the time a command takes to travel from your client, through the API server, to the device. Sending it at the moment an on-screen event occurs means the movement will follow after that delivery delay. For predictable events in a game or similar application, you may need to predict the movement and send the command early so it reaches the device close to when the movement should begin. Account for variation in delivery time; HDSP does not guarantee exact timing.

The endpoint names describe the fields they accept:

Method and path Required fields Movement
PUT /hdsp/xava xa, va Absolute position and velocity.
PUT /hdsp/xavp xa, vp Absolute position and relative velocity.
PUT /hdsp/xpva xp, va Relative position and absolute velocity.
PUT /hdsp/xpvp xp, vp Relative position and velocity.
PUT /hdsp/xat xa, t Absolute position and duration.
PUT /hdsp/xpt xp, t Relative position and duration.

Absolute position is measured in millimeters, absolute velocity in millimeters per second, and duration in milliseconds. Relative position xp is a floating-point fraction from 0 through 1, inclusive: 0.5 selects the midpoint. Relative velocity vp also uses 0–1, selecting a point between the configured minimum and maximum speeds. With limits of 32–400 mm/s, for example, vp=0.5 selects a nominal 216 mm/s.

Read the speed limits from GET /settings/slider. The nominal velocity is x_min_speed + vp * (x_max_speed - x_min_speed). vp=0 selects the minimum movement speed; it does not stop the slider. Use explicit stop control to interrupt movement, or stop_on_target=true to stop at the target.

A successful acknowledgment confirms command acceptance. Read position and speed through GET /slider/state to observe movement and target arrival.

To send that position and velocity, use PUT /hdsp/xpvp:

{"xp":0.5,"vp":0.2,"stop_on_target":true}

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

To request the midpoint over one second instead, use PUT /hdsp/xpt:

{"xp":0.5,"t":1000,"stop_on_target":true}

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Both examples set stop_on_target=true to stop at the target. It is optional and defaults to false. Another optional flag, immediate_rsp, defaults to false. Set it to true to receive a response without waiting for the device's reply; that response does not confirm the movement has completed.

HSP is another option for direct play and repeating patterns when you want to supply movement points and manage their buffer. For movements that must stay aligned with a media timeline, use HSSP, HSP, or STREAM and the timing approach below.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Keep playback synchronized

A video at ten seconds needs the movement intended for ten seconds, regardless of what time your computer or the device thinks it is. The server clock gives both sides a common reference.

For HSP, HSSP, and STREAM, distinguish these request fields:

Field Meaning
start_time Where to begin on the script or stream timeline, in integer milliseconds. Required for play requests.
current_time Your current media position, in integer milliseconds. Required for synctime requests.
server_time Your estimate of the server clock when making the request, in integer milliseconds. Optional in all play and synctime requests.

You can omit server_time; the server then uses its current time. Supplying a fresh estimate improves synchronization with external media by giving the server a time reference for the position you send. All three protocols' synctime requests also accept an optional numeric filter.

Synchronize the device clock

HSTP (Handy Simple Timing Protocol) synchronizes the device's clock with the server clock.

Call GET /hstp/clocksync?s=true with a device connection key. With s=true, the result is returned in the response and published over SSE. The default, s=false, publishes the result only over SSE. Handle any response error before continuing.

Open GET /hstp/clocksync in Swagger UI

curl --silent --show-error --fail-with-body \
  --header 'X-Api-Key: REPLACE_WITH_APPLICATION_ID' \
  --header 'X-Connection-Key: REPLACE_WITH_DEVICE_CONNECTION_KEY' \
  'https://www.handyfeeling.com/api/handy-rest/v3/hstp/clocksync?s=true'

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

GET /hstp/info reports device uptime in milliseconds as time, the server/device clock_offset, and the latest server/device round-trip delay as rtd. Your application estimates its own offset to the server separately, as described below.

You can read the user-adjusted offset with GET /hstp/offset and set it with PUT /hstp/offset using numeric offset in milliseconds. Negative integer offsets are supported. The setter acknowledges success with {"result":"ok"}; the getter returns an object containing a signed integer offset. Use integer milliseconds when setting an offset.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Estimate server time in your application

For closer synchronization with external media, estimate the difference between your application's clock and the server clock. GET /servertime requires no authentication and returns a top-level server_time in milliseconds:

Open GET /servertime in Swagger UI

curl --silent --show-error --fail-with-body 'https://www.handyfeeling.com/api/handy-rest/v3/servertime'

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Its success body has this shape:

{"server_time":1760000000000}

Read server_time directly. The value above is illustrative; this endpoint does not wrap it in result like device-state responses.

Use the shared Estimating server time guide for the measurement procedure, trimmed averaging, and offset-and-drift Kalman estimation. It includes complete reference implementations, worked examples, and sampling/recovery rules. Averaging is a simple choice for short stable sessions; Kalman tracks drift during ongoing playback.

Sample the media position and estimated server time for the same instant, then send integer milliseconds. This clock estimate is separate from the synctime.filter playback correction below. A media seek restarts the playback correction schedule without by itself invalidating the clock estimate.

GET /hstp/info reports device time, clock offset, and the most recent device/server round-trip delay. Device time is measured since boot, so it has a different starting point from server time. A timeline position such as start_time=10000 has a third meaning: ten seconds into your content.

Tune timing corrections

The optional filter in an HSP, HSSP, or STREAM synctime request controls how strongly playback timing adjusts to the position you send. Start with a larger value to bring playback into alignment quickly, then reduce it for gentler corrections once playback has settled.

For example, use the following request schedule:

Request When to send it Filter
First After 2000 milliseconds (2 seconds) 0.9, for a stronger initial correction.
Subsequent Every 10000 milliseconds (10 seconds) after that 0.5, for gentler ongoing corrections.

The request interval and correction strength are separate choices. These example values are application guidance, not API defaults. For each synctime request, send the current media position in current_time, the chosen filter, and a fresh server_time estimate if you are supplying one.

Restart synchronization after any playback change, including play, seek, skip, or resume. Reset the existing timer and return to the initial correction. With the example above, send the next request 2 seconds after the change with filter=0.9, then continue every 10 seconds with filter=0.5. Adapt the exact intervals and filter values to your application; the API does not require this particular cadence.

Use HSSP for URL-based script setup

Use the shared script-format reference for funscript and Handy CSV encoding, and the scripting guide for authoring and review.

If you do not have content ready, use a demo video and matching funscript. The setup example below uses the recommended 60 fps web MP4 pair's script.

HSSP is included in v3 mainly to preserve the familiar setup flow from HSSP in v2: provide a script URL, then control playback. Use it when that URL-based flow suits your integration.

Begin with the connection checks, then prepare the selected URL with PUT /hssp/setup. Wait for setup to succeed before sending any other HSSP request, including Stop or a state query. Once prepared, the application decides when to send Play and how device playback relates to the media's state.

Another use case is treating short scripts as motion sprites in games or similar interactive applications. A script defines a reusable movement effect that you trigger when a game event occurs. After setup, replay the effect with PUT /hssp/play and start_time=0. The script supplies the movement sequence, so your game does not need to generate each point as it runs. Standalone effects can omit server_time; include a fresh estimate when aligning an effect with an external timeline.

One script can contain several patterns. Keep an index of their start timestamps in milliseconds and select a pattern by passing its timestamp as start_time. For example, patterns starting at 0, 3000, and 6000 milliseconds can be selected without setting up a different script each time; start_time=3000 selects the second pattern.

Leave an idle gap after each pattern to give your client time to send PUT /hssp/stop before the next one begins. End patterns at a common resting position and hold that position through the gaps so the device remains still. Size each gap for client scheduling and command-delivery delay. Playback continues along the script unless the client stops it; a gap gives you time to send stop, rather than stopping playback automatically.

For most new script playback integrations, prefer the Stream API and STREAM protocol. Storing the script on the servers gives you a reusable stream_ref, lets you manage the stream and control access, and can make subsequent setups faster.

HSSP also caches scripts to speed up setup, but it must match the requested script to cached data. It may use an ETag or a stable check specific to the script's hosting service. If no suitable check can identify the script, the server may need to download it and compare its hash. Reusing a URL therefore does not guarantee that setup avoids another download.

After synchronizing the clocks, send PUT /hssp/setup with a script URL the Handy API server can retrieve:

{"url":"https://sweettecheu.s3.eu-central-1.amazonaws.com/synctest26/sync_video_60fps_web.funscript"}

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Replace the URL with your own supported script. In HSSP v3, the API server downloads the script at least once, so the URL must be reachable by that server. A host available only on your private network will not work, even if the device can reach it.

This differs from HSSP v2, where the device itself downloaded the script and could reach a script server on the same private network. In v3, the API server needs access to the script instead. If you cannot make your script host publicly accessible, use the Hosting API v2 for temporary hosting, then pass its returned download URL to PUT /hssp/setup.

The URL can also refer to a script token. When the server downloads a file it recognizes as a token, it locates the associated script and checks token validity and authorization for the intended device. If those checks pass, the server sends the actual script's movement data to the device. Uploading a valid token file to Hosting returns a token URL; use that URL unchanged in setup.

HSSP v3 is a layer in the API and backend on top of HSP (Handy Streaming Protocol), which streams movement points into the device's buffer. For HSSP, the server handles the device's threshold notifications and supplies more points as needed. GET /mode returns HSP mode 4 for both HSP and HSSP playback. Mode 1 is reserved for future use and is not returned for HSSP.

notify is optional and defaults to false, as in this example. HSSP clients do not need to implement the direct HSP event-driven refill workflow for playback to work.

Set notify=true if your client wants HSP events over SSE, for example to display playback state in its interface. The server continues to manage buffer replenishment either way; enabling notifications is an option for observing playback.

HSSP setup accepts a script URL only.

Once setup succeeds, send PUT /hssp/play with a fresh server-time estimate. Most HSSP integrations synchronize movement with media, so include the estimate as part of your normal playback requests:

{"start_time":0,"server_time":1760000000000,"playback_rate":1.0,"loop":false}

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

This starts at the beginning. A later start_time seeks forward. The server_time value above is illustrative: replace it with a fresh integer estimate from your chosen clock estimator, as described in Estimate server time in your application. Sample the media position for start_time and the server-time estimate for the same instant.

Media keeps moving while network checks run. Once preparation or session checks finish, read the latest media position and playback rate, then pair that position with a fresh server-time estimate. Routine clock updates do not mean the user changed their playback choice. Use the newest valid sample instead of waiting for it to remain unchanged; keep Stop, video changes, seeks and rate changes able to cancel superseded work.

Although the API accepts requests without server_time and then uses the server's current time, media-synchronized playback should supply the estimate to achieve the timing users expect. It lets the server relate the media position to when it was sampled, accounting for time spent delivering the request.

If you simply want to play a script without synchronizing it to media or another external timeline, you can omit server_time.

playback_rate is optional and defaults to 1.0: 0.5 plays at half speed and 2.0 at double speed. loop is optional and defaults to false. Use PUT /hssp/stop to stop playback and movement.

Adjust playback as it runs

Use PUT /hssp/synctime to correct timing during playback. Include a fresh server_time estimate sampled at the same instant as the media position in current_time. The filter strategy above uses a stronger first correction after two seconds, then gentler corrections every ten seconds. Adapt that strategy to your application; the API does not require that cadence.

Read state with GET /hssp/state. Pause with PUT /hssp/pause and resume with PUT /hssp/resume. Resume accepts optional pick_up, default false: false continues from the paused position; true picks up the live position.

Pause retains the playback clock. If the media continues while the device is paused, resume with pick_up=true to catch up to its current action. Stop discards the clock, so restart with play after a stop. See the playback-control comparison for the distinction and how to reproduce resume behavior using stop and play.

A browser can report several events for one playback choice. Keep successful device commands separate from what you want the player to do next. Once your Pause has been acknowledged, additional paused-media or seek events do not need another Pause. Repeating a command is not a guaranteed way to confirm its state. Distinguish a Pause you requested from a temporary pause while the device waits for more data.

For example, if your player keeps movement paused while the viewer seeks in a paused video, update the pending script position without sending Pause again for each seek event. When playback is requested, send Play using the latest position and a fresh server-time estimate. Serialize these changes, keep the latest choice, and reconcile the known session if a request's outcome is uncertain. A late response is evidence of device state; it should not restore an older playback choice.

Stopping HSSP retains the prepared script and its buffered points. Use HSSP controls for that managed session; direct HSP flush is not a cleanup operation for HSSP. State responses, including pause and resume, place the state in result.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Plan for buffering and seeks

In HSSP v2, the device needed the complete script before playback, so its buffer capacity limited the maximum script size. HSSP v3 is a layer on top of HSP: the server streams points into the device's buffer and refills or replaces them as needed. Like video streaming, the device keeps a working portion of the content ready for playback. The script's length is no longer capped by the device's buffer capacity.

The practical need for refills depends on the device:

Device Buffer capacity
Handy 2 series Up to 200,000 points; inspect max_points for the current capacity.
Handy 1 Approximately 1,000–4,000 points, depending on the device configuration.

Handy 2's buffer is large enough to hold an entire script in most cases. When the script fits, it can be pushed to the device in full during setup, making additional data delivery during playback unlikely. Handy 1's smaller buffer makes server-managed refills more relevant for longer scripts. Read max_points in the returned state for the current session's capacity.

The server also supplies replacement points when you seek to a position outside the buffered range. That can require another server/device round trip, which matters when a game jumps rapidly between motion patterns. Smaller scripts or HSP's direct buffer control may suit that case better. Inspect the returned state for the session's buffer capacity.

HSP point x and funscript action pos both use integer positions from 0 through 100, inclusive.

Keep the script URL on your backend

If you provide the content, your application's backend can call PUT /hssp/setup after checking the user's access. The Handy API server retrieves the script and prepares the device, while the browser or player receives no source script or script URL. Wait for setup to succeed before allowing HSSP playback controls; those controls can come from the client or your backend.

The script URL must remain reachable by the Handy API server. Use the usual Handy REST Application ID or client token and device addressing for setup. See playback without a script download for the comparison with STREAM and script tokens.

Supply your own stream of points

HSP gives you direct control over the points stored on the device. Use it for direct play, similar to HDSP, or for synchronized motion generated as your application runs. It also lets you decide exactly what is buffered and when to replace it.

For a file-based synchronization test, read a demo funscript and its matching video. Map each action's at and pos to point t and x, then follow the setup, buffering and playback steps below.

Use the fewest points needed to describe the movement. Peaks, valleys, start/end points and holds are often enough for simple strokes. Point density and device limits explains when intermediate points help, how unnecessary points consume buffer space, and how the device's capabilities and firmware configuration affect playback.

For continuous streaming, that control includes keeping the buffer supplied. Your client must handle the device's buffer notifications and send more points in time to avoid playback interruptions. HSSP handles those notifications and refills on the server.

Begin with PUT /hsp/setup. Read max_points in the returned state: capacity remains fixed for that session but may change at the next setup. The server assigns stream_id if you omit it. If you supply one, use an integer from 1 to 4294967295.

Complete setup before any other HSP operation, including Stop, state inspection, adding points or flushing. Connection checks alone leave this session unprepared.

Setup fully resets the HSP session, including its buffer and playback settings. Inspect the returned state and explicitly supply the options your play request needs.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Next, add points with PUT /hsp/add:

{"points":[{"t":0,"x":10},{"t":1000,"x":40}],"tail_point_stream_index":1,"flush":true}

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Each point has an integer time t, in milliseconds from stream start, and an integer position x from 0 through 100. This example supplies positions 10 and 40, one second apart. You can send at most 100 points per request.

The required tail_point_stream_index is the absolute index, within the whole stream, of the last point in the device buffer. Indexes are zero-based: the first point is 0, and the two-point example above ends at 1. Keep that absolute index distinct from an index within the device's current buffer.

flush=true clears existing points before adding the new ones; its default is false. If you append more points than the remaining capacity allows, the oldest buffered points are removed, including points that have not played yet. Plan refills so evicted points are no longer needed.

Start playback

Start with PUT /hsp/play, supplying start_time. You can add a fresh server_time estimate for closer synchronization with media. Optional playback rate, looping, and pause-on-starving default to 1.0, false, and false. An optional add field can embed an add-points request that runs before playback starts.

For continuous patterns, send an initial batch that covers the lookahead your application needs, either before Play or inside add. A single point is valid, but it cannot describe a repeating stroke. Count only points the device has acknowledged as available; generating points does not make them available to the device. Keep generated data separate from the transmit queue, and refill using the last acknowledged timestamp and absolute tail index. A valid later timestamp can still create an unintended gap if earlier movement was never transmitted. If your application displays a graph, for example, distinguish the planned pattern from the points already delivered.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use HSP for direct play

You can use HSP for direct play, much like HDSP, without calculating a server-time estimate. Once the HSP session is initialized, send PUT /hsp/play with an embedded add request, set flush=true to replace buffered points, and use start_time=0 with the first point at t=0. Omit server_time so the server uses its current time. Playback then begins as soon as possible; later points keep their timing relative to the stream's start.

Set loop=true to repeat the pattern. This example returns to its starting position after one second and repeats:

Open PUT /hsp/play in Swagger UI

{
  "start_time": 0,
  "loop": true,
  "add": {
    "points": [
      {"t": 0, "x": 10},
      {"t": 500, "x": 40},
      {"t": 1000, "x": 10}
    ],
    "tail_point_stream_index": 2,
    "flush": true
  }
}

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

To change the repeating pattern, send another play request with the replacement points and the same timing, flush, and loop settings. The embedded add runs before play, clearing the previous points before the new pattern begins. Omit loop or set it to false to play the points once. Omitting server_time alone does not make every point immediate: the point timestamps and start_time must still align.

Switch at the current pattern time

For a continuously generated pattern, keep one shared pattern clock when switching to another pattern. Generate the replacement points at that clock's current time and into the future. Setting both start_time and point timestamps back to zero would restart the pattern instead of following that clock.

You can establish an explicit timing reference with PUT /hsp/play and an embedded add: use flush:true to replace the old queue, set its absolute tail fields for the replacement points, and set start_time to the current pattern-clock position. Supply a fresh server_time estimate sampled for that same instant. For example, at 12.8 seconds use start_time:12800 and point timestamps on the same timeline, rather than restarting the pattern timeline. The new timing reference preserves the selected pattern's current phase. Matching setup remains valid; another setup is unnecessary.

Keep loop:false for a continuously generated timeline and continue ordinary refills with flush:false. Use pause_on_starving:false when the chosen application policy is to keep following an external clock through a shortage; use the held-time behavior when preserving the queued cadence is preferable. Queue-only replacement through Add uses the existing playback reference, as described below.

Keep the buffer supplied

Subscribe to SSE events before starting continuous HSP playback. These notifications tell your client when the device needs more data. If you filter the stream and wait for EventSource to open before Play, include device_status for an initial response, alongside the HSP events your client needs:

Event Meaning and client action
hsp_threshold_reached The configured point threshold has been reached. Append more points with PUT /hsp/add before playable data runs out.
hsp_starving There is no more playable data. Sent regardless of pause_on_starving. Supply the missing data; the threshold notification should normally let you refill before this happens.
hsp_paused_on_starving With pause_on_starving=true, playback has paused and stream time is held because data ran out. The device clock continues running. This is additional to hsp_starving. Supply more playable points.
hsp_resumed_on_not_starving With pause_on_starving=true, playback has resumed after playable data became available. Continue the normal refill cycle.

For normal refills, append points with flush=false, its default. Use flush=true when you intentionally want to replace buffered data. In PUT /hsp/add, flushing preserves the playback clock: the new points still belong to the existing timeline. You do not need another Play just because you replaced the buffer.

Two fields make this notification cycle useful:

  • tail_point_stream_index identifies the last buffered point in your overall stream. Keep it consistent with the points you supply; it is not a buffer-local index or a count of buffered points.
  • tail_point_threshold sets an absolute stream-index threshold for the next refill notification. Choose and update it to leave enough time for your client to receive the event and deliver more points before starvation. Set it sufficiently ahead of playback: the device ignores a threshold update if its target index has already passed when the update arrives.

Use a positive threshold with enough lead time for event delivery and refill. Zero is not a guaranteed notification on start. Treat the event as a refill signal rather than relying on an exact trigger instant.

Keep these values correct as you add or replace points and when starting or resuming continuous playback. HSP play accepts them in its embedded add request. You can also update the threshold separately with PUT /hsp/threshold; the returned state calls it tail_point_stream_index_threshold.

PUT /hsp/resume currently accepts only pick_up. Before resuming, use PUT /hsp/add to supply points and their tail index, and update the notification threshold through that add request or PUT /hsp/threshold. Do not put tail fields in the resume request.

Set pause_on_starving=true if you want playback to pause and stream time to wait during a shortage. The device clock keeps running. When new playable points arrive, playback resumes automatically from the held stream time. New point timestamps must be strictly after the last point in the buffer; do not shift them to account for the wait.

You can change the flag through PUT /hsp/pause/onstarving; its default is false. With false, stream time continues during starvation and points already in the past are skipped. Send points ahead of the current stream time; playback can continue when those playable points arrive.

For example, at playback rate 1, suppose the buffer ends at 2000 ms and the next batch arrives after a ten-second shortage. With the flag false, stream time has advanced to roughly 12000 ms, so points at 2500, 3000 and 3500 ms are already past. With the flag true, stream time was held and those points can play without adding ten seconds to their timestamps.

A starving event alone does not require Stop or a fresh Play. For continuous streaming, supply playable points and let playback recover. Your application can choose to stop, but that discards the playback clock. A paused state read can show current_time advancing even while logical stream time is held; use play_state and current_point alongside that reading rather than treating it as proof that refill points are stale.

Normal refill

The threshold should give your client enough time to deliver the next points while the device still has playable data. In this flow, the add request includes the correct tail index and the next notification threshold.

sequenceDiagram
    participant C as Your client
    participant A as Handy API server
    participant D as Device
    Note over C,A: HSP events subscribed over SSE
    loop Continuous HSP playback
        D->>D: Play buffered points
        D-->>A: Refill threshold reached
        A-->>C: hsp_threshold_reached (SSE)
        C->>C: Prepare next points and tail metadata
        C->>A: PUT /hsp/add (flush=false)
        A->>D: Append points and update threshold
        D->>D: Continue playback with data available
    end

If data runs out

A starving notification tells your client there is no more playable data, regardless of pause_on_starving. With the flag enabled, an additional paused notification reports that playback is waiting with stream time held. The device clock continues running.

sequenceDiagram
    participant C as Your client
    participant A as Handy API server
    participant D as Device
    D->>D: Playable data runs out
    D-->>A: Starving
    A-->>C: hsp_starving (SSE)
    Note over D: Device clock continues running
    alt pause_on_starving=true
        D->>D: Pause playback and hold stream time
        D-->>A: Paused on starving
        A-->>C: hsp_paused_on_starving (SSE)
    else pause_on_starving=false
        Note over D: Stream time continues and past points are skipped
    end
    C->>A: PUT /hsp/add with points for the playback timeline
    A->>D: Supply playable points
    opt pause_on_starving=true
        D->>D: Resume playback from held stream time
        D-->>A: Resumed after starvation
        A-->>C: hsp_resumed_on_not_starving (SSE)
    end
    opt pause_on_starving=false
        D->>D: Continue on the existing clock when future points arrive
    end

For HSSP, the server handles these notifications and supplies the points. HSSP clients do not need to implement the direct HSP event-driven refill workflow for playback to work.

Read state and control playback

GET /hsp/state reports buffered points and playback state. Its current_time is a live clock reading in milliseconds from stream start, captured when the state snapshot was generated. While playing, it advances with playback. During starvation pause, the reported reading can advance even though stream time is held, then realign when playback resumes. Schedule paused-starvation refills after the last buffered point's timestamp rather than treating an advancing paused reading as proof that those points are too late.

points counts stored buffer data, including played points. current_point is the zero-based buffer index of the next target; when it equals points, no target remains in that buffer. This buffer-local index differs from the absolute stream indexes in refill requests.

Choose between play, pause, resume, and stop

Control When to use it
PUT /hsp/play Start playback at the position supplied in start_time. It can follow either stop or pause.
PUT /hsp/pause Temporarily suspend playback, retaining the playback clock and paused position. Follow it with either resume or play.
PUT /hsp/resume Continue paused playback. With pick_up=false, the default, continue from the paused position; with pick_up=true, jump to where the stream would now be if it had kept playing.
PUT /hsp/stop Stop playback and device movement, discarding the playback clock. Restart with play; resume cannot follow stop.

For example, pause the device's movement while letting a video continue. Resume with pick_up=true when you want the device to catch up to the video's current action. Leave it false to continue the movement from where you paused. Both HSP and HSSP use the same pick_up flag.

If you use stop, your client must track the timing needed to reproduce those choices. Record the stream position before stopping, then call play with that saved start_time to continue from the stopped position. At normal playback speed (playback_rate=1.0), use the saved position plus the elapsed time since stopping to reproduce catch-up behavior. Use milliseconds for both values.

Use PUT /hsp/flush to clear buffered points explicitly. After a play, seek, skip, or resume, restart the synchronization sequence if your application is synchronizing playback with external media.

Use PUT /hsp/synctime for timing corrections. The agent reference covers the full state fields and controls.

To change pace during playback, send {"playback_rate":0.5} to PUT /hsp/playbackrate for half speed, or 2.0 for double speed. Enable repetition with PUT /hsp/loop and {"loop":true}; send false to disable it.

HSP pause and resume return the state inside a result envelope, like the other playback controls. Read current_time together with play_state and current_point; an advancing clock reading alone does not mean movement has resumed. Use pick_up=false to resume from the retained position, or true to catch up to the current live position.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Play stored scripts or live streams

STREAM plays stored scripts as well as live data, with delivery to the device handled by the server. For most new script playback integrations, it is the preferred option. You control playback through the Handy REST API without implementing HSP buffer replenishment yourself.

Use the demo video/script pairs if you have no script ready. Import the selected funscript through the Stream API first, then use its returned stream_ref for the device setup below.

All device models support STREAM, subject to the firmware requirements. On Oh, the device translates the movement into vibration.

Complete PUT /stream/setup before its other playback and state requests, including Stop. Creating a stream through the Stream API stores content; the Handy REST setup step separately prepares device playback.

For a prepared script, use the separate Stream API v0 to store its data on the servers. Keep the returned stream_ref and pass it to PUT /stream/setup whenever you want to set up playback of that stream again. Reusing the stored data can make subsequent setups faster by avoiding HSSP's need to identify the script from its URL. The Stream API provides separate data and editor keys for adding content and managing the stream.

Stream creation requires an Application ID issued for the Stream API; its client-token issuance is planned. Keep it separate from your Handy REST credential. The device controls below, including /stream/setup and /stream/play, still use your Handy REST Application ID or device client token and the device connection key. Creating a stream also returns a data_key for appending data and an editor_key for stream management; use each key in its intended context. The stream_ref identifies the content for device setup and does not replace those credentials.

You can also obtain an existing accessible stream_ref from the service supplying your content, including a stream used for live data. After synchronizing clocks, send PUT /stream/setup:

{"stream_ref":"REPLACE_WITH_ACCESSIBLE_STREAM_REFERENCE","notify":true}

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

stream_ref is required and must be a string. Optional notify defaults to false; true enables HSP notifications over SSE. Setup resets existing HSP state and returns the new state.

Start with PUT /stream/play, supplying integer start_time in milliseconds. Optional server_time uses the server's current time when omitted; add a fresh estimate for closer synchronization with external media. Optional playback rate, looping, and pause-on-starving default to 1.0, false, and false.

Use GET /stream/state to read state, PUT /stream/synctime to adjust timing, and PUT /stream/stop to stop playback and movement.

Multiple devices can use the same accessible stream. Creating and managing streams, storing script data, appending live data, and finalizing streams belong to the Stream API. Those operations are outside this Handy REST specification.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Prepare provider-owned streams

For content you supply, your backend can store the script through the Stream API and give the player only its stream_ref, rather than the script file or source URL. You can also keep that reference on the backend and call PUT /stream/setup there after checking the user's access. Once setup succeeds, the client can control the prepared playback session, or your backend can forward its controls.

Keep the Stream API data/editor keys on your backend, and use Handy REST credentials for device setup and playback. The shared playback comparison explains this approach alongside backend HSSP setup and script tokens.

Play repeating patterns

HRPP (Handy Repeating Pattern Protocol) plays patterns available on the device. All device models support it, subject to the firmware requirements. Patterns have two file types: audio and script. Oh supports both, while Handy devices support script only. Choose a pattern with a file type supported by your device.

Call GET /hrpp/patterns and choose a slot from result.patterns. The result is an object containing state and patterns, rather than a bare array. Activate the returned slot with PUT /hrpp/patterns/{slotNo}/activate, replacing {slotNo} with that slot number, then start playback with PUT /hrpp/start. The slot is an integer of at least 0.

Patterns also have an identifier named id. Use the returned slot when activating a pattern.

Change speed with PUT /hrpp/playbackrate and numeric playback_rate; 1.0 is normal speed. Change amplitude with PUT /hrpp/amplitude and numeric amplitude, described on a [0,1] scale. Neither request schema declares a default.

Read state with GET /hrpp/state; nr_of_patterns gives the count and playback_rate gives the rate. Use PUT /hrpp/stop to stop playback, and check the response and device state before sending further movement commands.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Use the curl example or linked Swagger UI operation if interactive controls are unavailable.

Address several devices

A single client can communicate directly with several devices. Send a separate Handy REST request for each device, using its connection key in X-Connection-Key. This lets you send the same command to several devices or control each one differently.

When you want to send the same command to a group, multicast is more efficient. Use the Channel API v1 to create a channel and add the devices, then send one supported Handy REST command with the channel reference in X-Connection-Key. Handy REST forwards the command to the channel's active subscribers, reducing the number of requests your client needs to make.

Some operations accept channel references; others require an individual device key. The endpoint index tells you which each operation accepts; check it before using a channel reference.

GET /info requires an individual device connection key. Channel v1 references return HTTP 200 containing error.name: NOT_SUPPORTED (141008) for this operation. Use each participant's actual device key for firmware and hardware checks. V1 also retains single-device alias behavior on supported operations; it does not add /info support.

Listen for device events

Server-Sent Events, or SSE, let your application hear about changes as they happen. device_status supplies initial status when the connection starts; device_connected and device_disconnected report changes in connectivity. Other events cover modes, protocol state, clock synchronization, and device conditions.

If your browser waits for the event connection to open before starting playback, include device_status in the events filter or leave the filter unset. That initial response avoids waiting for a playback event before playback has begun. It does not include the current mode or protocol state; obtain those with the mode-first flow.

For authentication, supply an Application ID or client token in query parameter apikey. For addressing, the backend accepts a device connection key or channel reference through either query parameter ck or header X-Connection-Key.

In a browser, use ck. Native EventSource accepts a URL and a withCredentials option, but does not offer custom request headers. Non-browser clients that support configurable headers can use X-Connection-Key instead. The HTML standard and MDN constructor reference describe the browser interface.

For example, a browser connection URL can be:

https://www.handyfeeling.com/api/handy-rest/v3/sse?apikey=CLIENT_TOKEN&ck=DEVICE_KEY&events=device_connected,device_disconnected

Replace the placeholders and URL-encode their values. events is an optional comma-separated filter; omit it to receive all event types. Keep Authentication Keys on the server. Swagger UI cannot exercise this connection.

Each SSE message has separate id, event, and data fields. The event field supplies the event name; the JSON in data contains connection_key and event-specific data. Use GET /hvp/state when you need the current HVP state.

An event connection may remain quiet; no fixed heartbeat interval is guaranteed. Apply a connection deadline separately from any application-specific inactivity policy.

An open event connection does not prove the device is reachable. A timed-out stop leaves the outcome uncertain. Restore access and read the device state before sending more movement commands; if access is still lost, check and stop the device locally as needed.

Handle the event names listed in the agent reference and OpenAPI specification, including the pause/resume-on-starving events. If an unexpected event name arrives, check that your client uses the current specification. Report a mismatch that remains as a possible API or specification bug.

Reconcile device state after reconnecting, and renew client tokens before expiry. Do not rely on event replay or Last-Event-ID to recover missed events.

Physical buttons and device modes

For firmware v4 and later, button_event reports unhandled button input. The active mode may consume an input to change a setting. A quiet raw-button subscription can therefore be normal while the device's physical controls are working.

Which physical inputs are handled locally or forwarded depends on the active mode and firmware.

Mode Value Physical controls
HAMP 0 Stroke and speed settings.
Reserved for future use 1 Not used for HSSP.
HDSP 2 Depends on device firmware.
Maintenance 3 Depends on device firmware.
HSP, including HSSP playback 4 Up/down adjust stroke; left/right adjust playback rate.
OTA 5 Depends on device firmware.
Button 6 Input handled locally is not forwarded as a raw button event.
Idle 7 Depends on device firmware.
Vibrate 8 Depends on device firmware.
HRPP 9 Depends on device firmware.

Handled input is not also forwarded as raw button_event. To investigate its effects, omit the events filter and compare mode and state readings before and after a press. Resulting notifications such as stroke_changed, hamp_state_changed, or hsp_state_changed may help. They describe changes, rather than a physical-input log; do not expect a notification for every press or a repeated setting.

The event-specific ButtonEvent payload uses numeric fields:

Field Values
button 0 power, 1 up, 2 left, 3 right, 4 down, 5 Wi-Fi.
event 0 pressed, 1 released, 2 short press, 3 long-press start, 4 long-press step, 5 long-press end.

For example, {"button":2,"event":2} describes a left-button short press if the firmware forwards it. Press and release stages can be handled differently. Power and Wi-Fi controls may also perform device-wide actions. Check the actual model, firmware, and reported mode before relying on a mapping.

Available modes depend on the device and firmware. STREAM is a playback API feature and HSTP provides clock synchronization; neither adds a numeric device mode to this list.

Handle errors and request limits

For every request, check the HTTP status and the response body. Many device operations return either result or error, and a device error can arrive with HTTP 200. A successful operation may have no result data. GET /servertime uses its own top-level response shape.

Read the success body for the operation you called. For example, a connection check returns {"result":{"connected":true}}, server time returns {"server_time":1760000000000}, and an HDSP position/time command can acknowledge with {"result":"ok"}. Handle error first, then decode the documented success shape. Requiring an object inside result for every response would reject valid replies.

Additional error.data can be an object or text, including an empty string. Inspect its type before reading structured fields.

A device timeout can look like this:

{"error":{"code":1002,"name":"DeviceTimeout","message":"Device timeout","connected":true}}

All errors share the same structure: required code and name, with optional message and data. Device errors additionally include connected, which reports the device's connection status. Other errors, such as those from token operations, do not require that field. Your error handler should work when message or data is absent.

A timeout leaves the outcome uncertain. Check state before repeating a movement command. Where an operation declares query parameter timeout, it is measured in milliseconds, defaults to 5000, and accepts values from 5000 to 60000.

The shared response definitions cover bad requests, authorization failures, missing resources, timeouts, throttling, and server errors. Each operation may list only some of them.

Confirm Stop before leaving

Keep an explicit Stop control available and wait for its acknowledgment when ending output. A request sent while a page closes is only best effort: the browser or network may disappear before it arrives. If Stop cannot be confirmed, say so and direct the user to the device controls.

Each protocol has its own playback-state values. Confirm Stop using the protocol you prepared:

Protocol Successful stopped response
HAMP result.play_state: 0
HSP, HSSP and STREAM result.play_state: 2
HVP result.enabled: false
HRPP result.play_state: 1

For HSP, HSSP and STREAM, play_state: 0 means not initialized, not stopped. Do not reuse HAMP's stopped-value check for these protocols. Their matching setup must already have succeeded before Stop.

After a timed-out movement request, inspect the known prepared session before repeating it. The original movement may already have executed. Recovery follows the same setup rules as ordinary playback; use a matching prepared session for Stop or state inspection, rather than setting up a replacement just to find out what happened.

Pace requests using the returned limits

When quota headers are present, use them to decide how quickly to send further requests:

Header Meaning
X-RateLimit-Limit Request limit per minute window.
X-RateLimit-Remaining Requests left in the current window.
X-RateLimit-Reset Seconds until the next reset.

Reduce requests as the remaining allowance falls, and account for the reset delay after throttling. The quotas shown in specification examples are illustrative; the returned headers describe your application's current allowance.

API version and reference

This guide covers Handy REST API v3, a stable API. Its OpenAPI specification has version 3.0.0 and uses OpenAPI 3.0.3.

Examples use the production API. The specification also lists v3-next, a pre-release environment that may change at any time. Check the base URL when switching environments.

For the full endpoint index and detailed request requirements, see the agent reference.