# 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](https://links.handyfeeling.com/docs-handy-rest-api-v3-agents) supplies the complete endpoint index and exact request requirements when you need more detail. All examples use the production API: ```text https://www.handyfeeling.com/api/handy-rest/v3 ``` For exact request and response schemas, use the [OpenAPI specification](https://links.handyfeeling.com/spec-handy-rest-api-v3). See [API version and reference](#api-version-and-reference) for version details. For browser or worker implementations, the [small JavaScript request helper](https://links.handyfeeling.com/docs-handy-rest-api-v3-agents#javascript-requests) shows device addressing, response parsing and error handling. ## Contents - [Request settings](#request-settings) - [Make your first request](#make-your-first-request) - [Understand the credentials](#understand-the-credentials) - [Check firmware and hardware](#check-firmware-and-hardware) - [Choose a protocol](#choose-a-protocol) - [Start with simple slider movement](#start-with-simple-slider-movement) - [Control vibration](#control-vibration) - [Send individual movements](#send-individual-movements) - [Keep playback synchronized](#keep-playback-synchronized) - [Use HSSP for URL-based script setup](#use-hssp-for-url-based-script-setup) - [Supply your own stream of points](#supply-your-own-stream-of-points) - [Play stored scripts or live streams](#play-stored-scripts-or-live-streams) - [Play repeating patterns](#play-repeating-patterns) - [Address several devices](#address-several-devices) - [Listen for device events](#listen-for-device-events) - [Handle errors and request limits](#handle-errors-and-request-limits) - [API version and reference](#api-version-and-reference) ## 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](https://user.handyfeeling.com/invite), then use the [user portal](https://user.handyfeeling.com) to create an Application ID. We will use that for the first requests; [other credential options](#understand-the-credentials) 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](https://links.handyfeeling.com/swagger-handy-rest-api-v3-connected) ```bash 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' ``` A connected device can return: ```json {"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](https://links.handyfeeling.com/swagger-handy-rest-api-v3-info) ```bash 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 `fw_version` and `fw_status` to make the [compatibility check](#check-firmware-and-hardware). Once the firmware is suitable, find out what hardware is available: [Open `GET /capabilities` in Swagger UI](https://links.handyfeeling.com/swagger-handy-rest-api-v3-capabilities) ```bash 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' ``` 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](https://links.handyfeeling.com/docs-guide-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: ```http 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](https://links.handyfeeling.com/swagger-handy-rest-api-v3-token-issue) ```bash 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](https://links.handyfeeling.com/docs-handy-rest-api-v3-agents#issue-and-renew-client-tokens). 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](https://handyverse.com/#/ota). | 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](https://links.handyfeeling.com/docs-guide-device-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. | ### 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](#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. ### 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](https://links.handyfeeling.com/swagger-handy-rest-api-v3-slider-stroke) ```bash 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' ``` [Open `PUT /hamp/start` in Swagger UI](https://links.handyfeeling.com/swagger-handy-rest-api-v3-hamp-start) ```bash 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' ``` [Open `PUT /hamp/velocity` in Swagger UI](https://links.handyfeeling.com/swagger-handy-rest-api-v3-hamp-velocity) ```bash 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' ``` 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](https://links.handyfeeling.com/swagger-handy-rest-api-v3-hamp-state) ```bash 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' ``` [Open `PUT /hamp/stop` in Swagger UI](https://links.handyfeeling.com/swagger-handy-rest-api-v3-hamp-stop) ```bash 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' ``` 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. ### 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: ```text 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. ## 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](https://links.handyfeeling.com/docs-guide-device-protocol-compatibility#protocol-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](https://links.handyfeeling.com/docs-handy-rest-api-v3-agents#hvp-vibration) explains how these device-dependent requirements are represented in the specification. ## 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`: ```json {"xp":0.5,"vp":0.2,"stop_on_target":true} ``` To request the midpoint over one second instead, use `PUT /hdsp/xpt`: ```json {"xp":0.5,"t":1000,"stop_on_target":true} ``` 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](#use-hsp-for-direct-play) 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. ## 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](https://links.handyfeeling.com/swagger-handy-rest-api-v3-clock-sync) ```bash 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' ``` `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. ### 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](https://links.handyfeeling.com/swagger-handy-rest-api-v3-server-time) ```bash curl --silent --show-error --fail-with-body 'https://www.handyfeeling.com/api/handy-rest/v3/servertime' ``` Its success body has this shape: ```json {"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](https://links.handyfeeling.com/docs-guide-server-time-estimation) 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](https://links.handyfeeling.com/docs-guide-script-formats) for funscript and Handy CSV encoding, and the [scripting guide](https://links.handyfeeling.com/docs-guide-scripting) for authoring and review. If you do not have content ready, use a [demo video and matching funscript](https://links.handyfeeling.com/docs-guide-demo-content#start-with-this-pair). 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](#connect-before-preparing-playback), 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](#play-stored-scripts-or-live-streams). 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](#keep-playback-synchronized), send `PUT /hssp/setup` with a script URL the Handy API server can retrieve: ```json {"url":"https://sweettecheu.s3.eu-central-1.amazonaws.com/synctest26/sync_video_60fps_web.funscript"} ``` 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](https://links.handyfeeling.com/docs-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](https://links.handyfeeling.com/docs-guide-script-tokens#a-token-as-a-file-or-url). 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: ```json {"start_time":0,"server_time":1760000000000,"playback_rate":1.0,"loop":false} ``` 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](#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](#tune-timing-corrections) 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](#choose-between-play-pause-resume-and-stop) 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`. ### 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](https://links.handyfeeling.com/docs-guide-script-tokens#offer-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](https://links.handyfeeling.com/docs-guide-demo-content#choose-the-playback-flow). 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](https://links.handyfeeling.com/docs-guide-script-formats#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. Next, add points with `PUT /hsp/add`: ```json {"points":[{"t":0,"x":10},{"t":1000,"x":40}],"tail_point_stream_index":1,"flush":true} ``` 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 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](https://links.handyfeeling.com/swagger-handy-rest-api-v3-hsp-play) ```json { "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 } } ``` 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](#listen-for-device-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. ```mermaid 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. ```mermaid 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](#tune-timing-corrections) if your application is synchronizing playback with external media. Use `PUT /hsp/synctime` for timing corrections. The [agent reference](https://links.handyfeeling.com/docs-handy-rest-api-v3-agents#hsp-dynamic-points-and-buffer-control) 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. ## 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](https://links.handyfeeling.com/docs-guide-demo-content) 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](https://links.handyfeeling.com/docs-guide-device-protocol-compatibility#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](https://links.handyfeeling.com/docs-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](#keep-playback-synchronized), send `PUT /stream/setup`: ```json {"stream_ref":"REPLACE_WITH_ACCESSIBLE_STREAM_REFERENCE","notify":true} ``` `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](https://links.handyfeeling.com/docs-stream-api-v0). Those operations are outside this Handy REST specification. ### 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](https://links.handyfeeling.com/docs-guide-script-tokens#offer-playback-without-a-script-download) 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](https://links.handyfeeling.com/docs-guide-device-protocol-compatibility#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. ## 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](https://links.handyfeeling.com/docs-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](https://links.handyfeeling.com/docs-handy-rest-api-v3-agents#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](https://links.handyfeeling.com/docs-channel-api-v1#single-device-alias-responses) 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](#read-the-active-protocol-state). 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](https://html.spec.whatwg.org/multipage/server-sent-events.html#the-eventsource-interface) and [MDN constructor reference](https://developer.mozilla.org/en-US/docs/Web/API/EventSource/EventSource) describe the browser interface. For example, a browser connection URL can be: ```text 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](https://links.handyfeeling.com/docs-handy-rest-api-v3-agents#sse-events) 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: ```json {"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](https://links.handyfeeling.com/spec-handy-rest-api-v3) 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](https://links.handyfeeling.com/docs-handy-rest-api-v3-agents).