Skip to content
Handyverse documentation

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

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

Documentation 2026.11.15.1 · Tag docs-2026.11.15.1 · Version and checksums

The Handy REST API v3: agent reference

Instructions for agents integrating with The Handy REST API v3. For the explanatory walkthrough, use the human guide.

Use the API overview for agents to choose complementary APIs and find their instructions.

Examples target the production API. The v3-next server is a pre-release environment that may change at any time. This reference does not establish behavior for later API versions.

API reference Value
API Handy REST API v3 (stable); specification version 3.0.0
OpenAPI format 3.0.3
Production base URL https://www.handyfeeling.com/api/handy-rest/v3
OpenAPI specification Request and response schemas
Developer resources Documentation home, Swagger UI

This reference documents methods, paths, operation identifiers, authentication, and request/response schemas for API integration.

For substantial integrations, consider generating a client in your project's preferred language using OpenAPI Generator and this API's OpenAPI spec. Follow this guide for authentication, workflows, and constraints that generated code may not enforce.

Documentation updates

Published Markdown downloads include docs_version, docs_tag, docs_revision, body_sha256, and an absolute updates URL in their opening YAML metadata. Before starting an integration or generating a client, fetch that update manifest and confirm its api_id and api_version. Compare docs_revision to detect changes to this API's guides, spec, or selected shared references; a publication tag can change without changing API content.

For an update, fetch agent_reference.url and verify the complete download against agent_reference.sha256. The embedded body_sha256 covers the exact UTF-8 bytes after the closing metadata delimiter (\n---\n), including trailing whitespace. Verify the spec and shared references against the manifest's file checksums before using them together. If a deployment changes during download, re-fetch the manifest and retry; keep the last verified copy until the update is complete. If offline or an update check fails, use the last verified copy and report that freshness could not be checked. These are documentation requests, not device API operations.

Agent reading order

  1. Read Compatibility before proposing device operations.
  2. Locate the exact method, path, operationId, authentication, and addressing parameter in the endpoint index.
  3. Read the relevant protocol section and referenced OpenAPI schemas before constructing a payload. Enforce conditional requirements in extension metadata as well as standard schema fields. Keep required fields, recommendations, defaults, and units distinct. For HSP, HSSP and STREAM, matching setup must succeed before every other protocol operation, including Stop and state queries. See Connection and session preparation.
  4. For HSP, HSSP, and STREAM play/synctime requests, omitted server_time defaults to the server's current time. Supply a fresh integer server-time estimate when external synchronization accuracy matters; start_time=0 is a valid timeline position.
  5. Use the documented units and constraints; do not infer protocol support from hardware capabilities alone.
  6. Use Device and protocol compatibility for model availability, movement output and firmware requirements. Do not infer protocol support from physical slider count.

The human guide explains the same API. This reference supplies the complete operation index and integration requirements.

Contents

Compatibility

Device control requires firmware v4 or later and hardware that supports the selected operation. Start with GET /connected, then GET /info. Inspect fw_version and fw_status before proceeding. fw_status reports the server's assessment of firmware currency and update requirements; service compatibility is a separate decision. Check GET /capabilities only after the required-update and service-compatibility checks pass; capabilities include slider count, LRA/ERM motor counts, battery, and external memory.

Capabilities describe physical hardware, not a complete protocol-support list. Oh accepts slider-protocol commands and translates their movement into vibration on the device. Do not reject Oh from HAMP, HDSP, HSP, HSSP or STREAM solely because capabilities.slider is 0. Use HVP when direct amplitude/frequency control is wanted; retain firmware and operation-availability checks.

GET /settings/slider is physical-slider configuration: request it only when capabilities.slider > 0. Oh's translated protocols do not require it and Oh does not supply these settings. Virtual GET /slider/stroke limits are a separate supported control; do not reject Oh movement because the physical-settings endpoint is unavailable.

The shared compatibility matrix covers protocol availability, movement output, HRPP file types, firmware requirements and the hardware ID/name list. It is the common reference for both human and agent guides.

fw_status Name Meaning
0 UP_TO_DATE Server considers firmware up to date; still apply service compatibility requirements.
1 UPDATE_AVAILABLE Server knows of a newer version; service determines whether installed firmware is supported.
2 UPDATE_REQUIRED Critical fix required; block further device interaction and direct the user to the updater.

Apply this policy before device commands:

  1. If fw_status == 2, block further device interaction and direct the user to the firmware updater. A service-specific compatibility rule cannot override this critical-update requirement.
  2. For fw_status == 1, use the third-party service's compatibility policy. A latest-only policy requires an update. A dynamic policy checks fw_version against supported versions and feature requirements, allowing compatible installed firmware to continue.
  3. For fw_status == 0, apply the service's firmware and hardware requirements before proceeding. Server currency alone does not establish service compatibility.

Latest-only is the simplest policy, but may impose unnecessary updates on users whose installed firmware already supports the service. Dynamic compatibility can avoid that interruption while enforcing the service's actual requirements.

For older firmware, three device operations are available: GET /connected, GET /info, and GET /sse. SSE requires firmware v3 or later and provides device_status or device_connected for v3 devices. Other device operations require supported firmware. These exceptions do not waive authentication or the block after UPDATE_REQUIRED.

Relevant OpenAPI schemas: #/components/schemas/DeviceInfo, FirmwareStatus, and DeviceCapabilities under #/components/schemas/.

Device session IDs

Successful GET /sids (getDeviceSessionIds) responses always include boot_session_id, socket_session_id, and mode_session_id as integer fields in result. All three are required in DeviceSessionIds.

  • boot_session_id: random value assigned on each boot.
  • socket_session_id: connection counter starting at zero; increments on each server connection and resets on boot.
  • mode_session_id: mode-change counter starting at zero; resets on boot.

The string session_id in GET /info is a separate field.

Read-only mode and message statistics

GET /mode returns the selected mode from DeviceModeValue and optional numeric mode_session_id. Use /sids for boot, socket, and mode-session counters.

GET /statistics uses DeviceStatisticsTimestamp, an object with integer seconds (Unix epoch UTC) and integer nanos in [0,999999999]. Unix milliseconds are seconds * 1000 + nanos / 1000000. This wire format is separate from the shared DateTime string type. Message counters are total_msgs, dropped_msgs, and acked_msgs; only timestamp is required in DeviceStatistics.

Select device mode

Prefer PUT /mode2 with required integer mode; it returns a DeviceMode object with optional mode_session_id. Deprecated PUT /mode takes the same request field and returns a string acknowledgment.

See Physical buttons and device modes for mode values and button behavior. Available modes and physical controls depend on the device and firmware.

Read the active protocol state

Read GET /mode first, then request the state belonging to the returned mode. For example, mode 0 uses GET /hamp/state, and mode 8 uses GET /hvp/state. Protocol entry commands and state GETs can select their mode; requesting another protocol's state can switch modes and interrupt playback. Parameter setters must not be assumed to select a mode. Do not poll all protocol state endpoints to discover which is playing.

HSP, HSSP and STREAM require their matching setup before other protocol commands; commands before setup fail. This includes Stop and state queries: neither initializes a session. After setup, use that workflow's state endpoint. Do not run setup merely to inspect an existing session, because setup replaces its state/buffer. When monitoring, use the known active protocol/session and refresh GET /mode when a mode-change event arrives.

Both HSP and HSSP report mode: 4 (HSP). HSSP is an API/backend layer over HSP, so the device mode alone cannot distinguish those workflows. For your prepared HSSP session, continue using GET /hssp/state and HSSP controls when mode 4 is reported. Device mode 1 is reserved for future use; it is not returned for HSSP playback. Device mode and playback play_state are separate fields.

The initial SSE device_status contains connection status and device information, not an initial mode/state snapshot. Obtain the current mode and matching state with the flow above.

Quickstart

Prerequisites: a registered HandyFeeling user account, an Application ID, and the device's connection key. Register through the registration page, then create an Application ID in the user portal. The account access token is for account management and is not an API credential.

Replace the placeholders below. These commands only inspect the device.

HANDY_API_BASE='https://www.handyfeeling.com/api/handy-rest/v3'
HANDY_API_CREDENTIAL='REPLACE_WITH_APPLICATION_ID'
HANDY_DEVICE_KEY='REPLACE_WITH_DEVICE_CONNECTION_KEY'

curl --silent --show-error --fail-with-body \
  --header "X-Api-Key: ${HANDY_API_CREDENTIAL}" \
  --header "X-Connection-Key: ${HANDY_DEVICE_KEY}" \
  "${HANDY_API_BASE}/connected"

A representative response is:

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

If result.connected is false, wait for the device to connect. If an error object is present, handle it before continuing. HTTP success alone is insufficient; see Errors.

curl --silent --show-error --fail-with-body \
  --header "X-Api-Key: ${HANDY_API_CREDENTIAL}" \
  --header "X-Connection-Key: ${HANDY_DEVICE_KEY}" \
  "${HANDY_API_BASE}/info"

curl --silent --show-error --fail-with-body \
  --header "X-Api-Key: ${HANDY_API_CREDENTIAL}" \
  --header "X-Connection-Key: ${HANDY_DEVICE_KEY}" \
  "${HANDY_API_BASE}/capabilities"

Run the capabilities request after checking Compatibility. Then choose a protocol. Control examples below assume these checks passed.

Connection and session preparation

Keep connection checks separate from protocol setup. An application's Connect action can validate /connected, read /info, apply firmware policy and then read /capabilities. Those checks do not initialize HSP, HSSP or STREAM. Do not unconditionally send a protocol Stop or query its state during first connection.

Client context Next operation
Connection checked; no matching setup has succeeded Choose the workflow and its input, then call its setup.
HSP selected Complete PUT /hsp/setup before add, flush, play, stop or state operations.
HSSP selected Complete PUT /hssp/setup with the script URL before play, stop, pause, resume, synctime or state operations.
STREAM selected Complete PUT /stream/setup with an accessible stream_ref before its playback or state operations.
Matching setup succeeded; media is paused Waiting for media playback before Play is a common default for media synchronization. The application and user choose whether device playback follows the media's pause state.
The application needs to stop a prepared session Use that workflow's Stop and check its response.

Starting output and coupling device playback to media are application policies, not API requirements. The application may provide a Start control, follow media play/pause, or allow independent device playback according to its design and user preferences. Matching protocol setup remains required in every case.

Track the prepared protocol and session identity in the client. These are client bookkeeping, not extra API request fields. Restored credentials establish access, not proof that the previous session is still prepared. When recovering a known session, read /mode first and use the matching state only with a valid session context. Prepare a new session when the application needs to replace the old one; setup replaces its state and buffered data.

For a known prepared HSP or HSSP session, track successful transport commands and their returned state separately from desired media intent. Once this client's Pause has been acknowledged as paused (3), duplicate paused-media or seek events do not require another Pause. Similarly, a confirmed Stop (2) needs Play to restart, not another Pause. Do not assume repeated Pause calls are idempotent. A paused media seek can update the desired script position while retaining that confirmed Pause; construct Play from the latest position and a fresh server-time estimate when playback is requested. Resume remains for a retained paused clock; after Stop, use Play.

Keep the cause of a pause in this bookkeeping: starvation can also hold playback and resume automatically when data arrives. An arbitrary state snapshot showing a pause is not by itself proof that this client's manual Pause intent was applied. Use the known session, command acknowledgments and relevant events when reconciling uncertainty.

Serialize writes and coalesce media events into the latest desired transition rather than sending one command for every event. Record successful responses as device-state evidence without allowing an old response to restore superseded intent. If a request outcome is uncertain, reconcile the known matching session before choosing another transition. Preserve cancellation on Stop, disconnect and target changes; ordinary advancing media samples still do not invalidate a pending Play. These are client-state recommendations, not new request fields or a promise of endpoint idempotence.

JavaScript requests

This small browser/worker helper uses an Application ID for device requests. Call native fetch through globalThis; if you inject it as a stored transport, bind it to globalThis first. Browser-native receiver checks can be hidden by a mocked transport, so also exercise the application's actual browser path.

function makeDeviceClient(applicationId, connectionKey) {
  const base = "https://www.handyfeeling.com/api/handy-rest/v3";
  return async function request(path, method = "GET", body) {
    const headers = {
      "X-Api-Key": applicationId,
      "X-Connection-Key": connectionKey,
    };
    if (body !== undefined) headers["Content-Type"] = "application/json";
    const response = await globalThis.fetch(base + path, {
      method,
      headers,
      ...(body === undefined ? {} : {body: JSON.stringify(body)}),
    });
    const payload = await response.json();
    if (!response.ok || payload.error) {
      const error = payload.error;
      throw new Error(error?.message || error?.name || `HTTP ${response.status}`);
    }
    return payload.result;
  };
}

The returned result can be an object, a string acknowledgement or another shape declared by the operation. Do not assume every successful command returns device state. For a client token, use Authorization: Bearer CLIENT_TOKEN instead of X-Api-Key, retaining device addressing. Authentication Keys belong on the application server and do not authorize device controls.

Authentication and device addressing

Credential types

Sign up and sign in at the user portal, then issue an Application ID (application_id) or Authentication Key (authentication_key) for Handy REST. If your account cannot issue credentials for an API, contact platform support about access to that API. See Developer access for shared signup and credential guidance. The operation requirements below govern their use in Handy REST.

Credential Where used Transport Scope
Account access token User portal Account login Account management; not REST API authentication.
Application ID (application_id) Browser, mobile app, or server X-Api-Key: APPLICATION_ID Device API operations. Public exposure still attributes usage to your account.
Authentication Key (authentication_key) Server Authorization: Bearer AUTHENTICATION_KEY Administrative operations only, such as client-token issuance. Device endpoints reject it. Keep it out of client code.
Client token Browser, mobile app, or server Authorization: Bearer CLIENT_TOKEN Device API operations with expiry and optional restrictions.

The OpenAPI spec's global security alternatives are ApiKeyAuth (Application ID) or BearerAuth (client token), not both together. Device endpoints reject Authentication Keys, including in server-originated requests. Use the credential's documented header. GET /servertime explicitly requires no authentication. GET /auth/token/issue uses the separate ApplicationKeyAuth bearer scheme; an Application ID or client token does not authorize token issuance. GET /sse uses its own query authentication scheme for an Application ID or client token.

For device requests using a client token, replace the X-Api-Key header in the quickstart with:

Authorization: Bearer REPLACE_WITH_CLIENT_TOKEN
X-Connection-Key: REPLACE_WITH_DEVICE_CONNECTION_KEY

Issue and renew client tokens

Issue tokens from your server using GET /auth/token/issue (issueToken):

HANDY_AUTHENTICATION_KEY='REPLACE_WITH_SERVER_SIDE_AUTHENTICATION_KEY'

curl --silent --show-error --fail-with-body --get \
  --header "Authorization: Bearer ${HANDY_AUTHENTICATION_KEY}" \
  --data-urlencode 'ttl=3600' \
  --data-urlencode "to=${HANDY_DEVICE_KEY}" \
  "${HANDY_API_BASE}/auth/token/issue"
Query field Required Contract
ttl No Integer seconds; default 3600 (1 hour), minimum 60 (1 minute), maximum 86400 (24 hours).
to No Bind the token's use to a specific device connection key.
ip No Restrict originating client IP.
origin, r, ua No Restrict Origin, Referer, or User-Agent prefixes respectively.
al, ae, cc No Restrict Accept-Language, Accept-Encoding, or Cache-Control values.

The device connection key, client IP address, and selected client headers form a lightweight client fingerprint that narrows token use to the intended device and client environment. Requests must satisfy the restrictions configured at issuance. These restrictions do not turn client-controlled headers into a strong identity guarantee.

The AuthTokenResponse.result contains token_ref, created_at, expires_at, token, and renew. Use token for bearer authentication. Follow the returned renew URL before expiry; do not reconstruct it. Renewal extends validity without changing the original restrictions. After expiry, both token and renewal URL are invalid and a new token must be issued.

Cached-session startup must check expiry before choosing a recovery path. Reuse a valid token and renew before expiry when needed. For an expired token, request fresh issuance through the application's backend/token proxy with saved issuance configuration; do not retry its expired renewal URL. Keep Authentication Keys server-side.

Device and channel references

Device operations need addressing in addition to authentication, including when a client token is restricted to a device.

OpenAPI parameter Header Accepted value
ConnectionKey X-Connection-Key Device connection key.
DeviceReference X-Connection-Key Device connection key or channel reference, such as chref:....

Use the endpoint index to see which parameter each operation declares. Do not assume that every device operation accepts a channel reference. Channel management belongs to the separate Channel API v1. SSE accepts either query parameter ck or header X-Connection-Key; consult SSE events for client-specific usage.

GET /info requires an individual device connection key. A Channel v1 reference returns HTTP 200 with error.name=NOT_SUPPORTED, code 141008. V1 single-device alias behavior applies only to supported operations and does not add /info support. Use participant device keys for firmware/hardware checks.

Choosing a protocol

Protocol Use case Timing Data delivery
HAMP (Handy Alternate Motion Protocol) Repeated slider movement with adjustable speed and stroke Immediate control Start/stop and parameter updates.
HVP (Handy Vibration Protocol) Vibration on supported hardware Immediate control Amplitude, frequency, and device-dependent position.
HDSP (Handy Direct Streaming Protocol) Interactive movements sent individually No built-in synchronization Client sends immediate position/velocity or position/time commands.
HSSP (Handy Synchronized Script Protocol) Preserve the v2-style URL-based script setup flow Server-clock synchronization Server fetches or identifies cached script data, then delivers points to the device.
HSP (Handy Streaming Protocol) Direct play or dynamic synchronized points with direct buffer control Server-clock reference; client server-time estimate optional Client adds points and handles buffer replenishment.
STREAM (Handy Stream Protocol) Preferred for most new script playback integrations; also supports live data Server-clock synchronization Separate Stream API stores script data or creates live data; reuse its returned stream_ref for setup. Server handles delivery.
HRPP (Handy Repeating Pattern Protocol) Repeating patterns available on the device Pattern playback control Select a returned pattern slot, then start and adjust playback.

HAMP, HVP, and HDSP do not require the synchronized playback workflow. HSSP, HSP, and STREAM share device buffer state concepts. Check the device's capabilities and firmware support before choosing a protocol.

Units and clock synchronization

Units

Value Unit or representation Usage
HAMP velocity Number [0,1], inclusive; fraction of configured minimum-to-maximum speed range Zero selects the configured minimum movement speed, rather than stop.
Slider/HAMP stroke min, max Relative numbers [0,1], inclusive Both fields are required and bounded by the request schemas; fractional values are valid.
HDSP xa, va Millimeters, millimeters/second Hardware-dependent absolute limits are not specified.
HDSP xp Number [0,1], inclusive; relative position fraction 0.5 is the midpoint.
HDSP vp Number [0,1], inclusive; fraction of configured minimum-to-maximum speed range Nominal speed is x_min_speed + vp * (x_max_speed - x_min_speed); zero selects minimum movement speed, not stop.
HDSP t Milliseconds, number Required with xa for /hdsp/xat or xp for /hdsp/xpt.
HSP point x, funscript action pos Integers [0,100], inclusive The minimum is 0 and the maximum is 100.
Point t, action at, start_time, current_time Milliseconds relative to script/stream start These are not wall-clock timestamps.
server_time Integer estimated server time in milliseconds Wall-clock reference used for synchronized commands.
HVP amplitude, frequency, position Number [0,1], integer Hz [0,10000], relative number [0,1] (0–100%) Handy requires all three fields; Oh requires amplitude and frequency.
Token ttl, rate-limit reset Seconds Separate from millisecond timing fields.
Device time from /hstp/info Milliseconds since device boot Different clock origin from server time.

Synchronize device and client clocks

Prerequisites: a connected compatible device, API authentication, and a device connection key. HSTP (Handy Simple Timing Protocol) synchronizes the device clock with the server clock. Its operations use ConnectionKey, not a channel reference.

  1. Synchronize the device with GET /hstp/clocksync?s=true (clockSync). With s=true, the result is returned synchronously and also published over SSE. The default s=false only publishes the result over SSE. Inspect the response for errors before proceeding.
  2. Estimate the client-to-server offset using GET /servertime (getServerTime). Its response is {"server_time":...}, without the device result envelope.
  3. Implement trimmed averaging or offset-and-drift Kalman estimation using the shared Estimating server time reference. It specifies measurement/clock bases, initialization, equations, executable code, worked values, and freshness/reset rules.
  4. Obtain a valid initial estimate, then evaluate it at the media-position sampling instant. Send a fresh integer server_time for each synchronized request.

Use a consistent client clock basis when calculating a sample. Refresh the estimate when its clock or network assumptions change; neither method removes unknown path asymmetry. A playback seek/play/resume restarts the playback correction schedule without automatically rebuilding the clock estimate. synctime.filter is a separate numeric playback-correction strength, not a clock-estimator selector.

curl --silent --show-error --fail-with-body \
  --header "X-Api-Key: ${HANDY_API_CREDENTIAL}" \
  --header "X-Connection-Key: ${HANDY_DEVICE_KEY}" \
  "${HANDY_API_BASE}/hstp/clocksync?s=true"

curl --silent --show-error --fail-with-body "${HANDY_API_BASE}/servertime"

Recalculate the offset when synchronization degrades, clocks drift, or network conditions change. GET /hstp/info exposes device uptime in milliseconds, the server/device clock offset, and the most recently observed server/device round-trip delay. The client/server round trip used by the estimator is a separate measurement. GET/PUT /hstp/offset reads or sets the user-adjusted device offset; the set payload requires numeric offset in milliseconds.

GET /hstp/offset returns a signed integer offset. PUT /hstp/offset accepts numeric offset in milliseconds; use integer milliseconds in examples and integrations.

HSTP offset PUT returns {"result":"ok"}, while GET returns an object. Use each operation's declared result type; the shared DeviceResponse envelope does not constrain all results to objects.

Request Required timing fields in the OpenAPI spec
PUT /hsp/play, PUT /hssp/play, PUT /stream/play start_time.
PUT /hsp/synctime, PUT /hssp/synctime, PUT /stream/synctime current_time; numeric filter is optional.

In all six requests, server_time is an optional integer in milliseconds. Omission uses the server's current time as a runtime default; no fixed timestamp is the default. Supply a fresh estimate for more accurate synchronization with external media. This applies to all synchronized protocols.

Tune timing corrections

For HSP, HSSP, and STREAM synctime, larger filter values produce stronger, quicker timing corrections; smaller values relax subsequent corrections. Use a stronger initial correction and a gentler setting afterward. For example:

Request Client schedule Filter
First After 2000 ms (2 seconds) 0.9.
Subsequent Every 10000 ms (10 seconds) afterward 0.5.

Request intervals and correction strength are separate choices.

Send the current media sample as current_time, the selected filter, and a fresh server_time estimate when supplied. Restart synchronization after every playback change, including play, seek, skip, or resume. Reset the existing timer and initial correction stage so the schedule is anchored to the latest change. For the example above, the next request is 2 seconds after that change with filter=0.9; subsequent requests use filter=0.5 every 10 seconds. The exact cadence and filter values are client guidance, not API requirements. filter is optional and numeric; do not infer a backend default or numerical bounds from the examples.

Protocol guides

Each recipe assumes the quickstart checks passed. JSON blocks are request bodies for the adjacent method and path. Play examples omit optional server_time to use the server's current time; add a fresh integer estimate for more accurate external synchronization. Their start_time=0 begins at the timeline's start. Device responses use the shared envelope.

HAMP: Alternate slider motion

Purpose: repeated motion controlled by speed and stroke; Oh translates it into vibration. Prerequisites: supported Handy or Oh hardware/firmware, authentication, and device addressing. Physical slider count alone is not a protocol-support check.

PUT /hamp/start is HAMP's setup/entry command: it selects HAMP mode 0 and starts movement. GET /hamp/state also selects HAMP mode and returns its state. HAMP-specific setters require HAMP to be entered first; a setter such as PUT /hamp/stroke is not an entry command.

  1. Set the global stroke with PUT /slider/stroke (setStroke).
  2. Enter and start HAMP with PUT /hamp/start (startHamp); this resets normalized velocity to 0 for safety, replacing any velocity set before Start, and begins minimum-speed movement.
  3. After each successful Start, apply the requested speed with PUT /hamp/velocity (setHampVelocity).
  4. Stop with PUT /hamp/stop (stopHamp).
curl --silent --show-error --fail-with-body --request PUT \
  --header "X-Api-Key: ${HANDY_API_CREDENTIAL}" \
  --header "X-Connection-Key: ${HANDY_DEVICE_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"min":0.1,"max":0.9}' "${HANDY_API_BASE}/slider/stroke"

curl --silent --show-error --fail-with-body --request PUT \
  --header "X-Api-Key: ${HANDY_API_CREDENTIAL}" \
  --header "X-Connection-Key: ${HANDY_DEVICE_KEY}" \
  "${HANDY_API_BASE}/hamp/start"

curl --silent --show-error --fail-with-body --request PUT \
  --header "X-Api-Key: ${HANDY_API_CREDENTIAL}" \
  --header "X-Connection-Key: ${HANDY_DEVICE_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"velocity":0.2}' "${HANDY_API_BASE}/hamp/velocity"

curl --silent --show-error --fail-with-body --request PUT \
  --header "X-Api-Key: ${HANDY_API_CREDENTIAL}" \
  --header "X-Connection-Key: ${HANDY_DEVICE_KEY}" \
  "${HANDY_API_BASE}/hamp/stop"

These are separate requests: inspect each response and proceed only on success. HAMP-specific limits from PUT /hamp/stroke apply inside the global slider stroke. Both stroke bodies require numeric min and max. The effective normalized position is global_min + local_position * (global_max - global_min). For global [0.1,0.9] and HAMP [0.1,1], the effective region is [0.18,0.9].

To configure HAMP-specific stroke before starting, deliberately enter HAMP with GET /hamp/state, inspect the returned state, then send PUT /hamp/stroke, PUT /hamp/start, and PUT /hamp/velocity, in that order. This leaves the global stroke settings unchanged. The state GET changes mode, so it is an intentional entry step rather than passive inspection of another active protocol.

The velocity reset is an intentional safety measure: each Start begins at the configured minimum instead of reusing a previous higher speed. A velocity set before Start is replaced; apply the requested velocity after every successful Start. Normalized 0 is still moving, not stopped.

Inspect GET /hamp/state or hamp_state_changed events. HampPlayState is 0 stopped and 1 playing. HAMP velocity uses [0,1], inclusive, in setters and state responses.

Nominal speed is x_min_speed + velocity * (x_max_speed - x_min_speed), using GET /settings/slider; the normalized state value is not measured mm/s. Zero velocity still moves at the configured minimum speed. Use /hamp/stop and verify play_state=0 to stop.

GET /slider/state and GET /slider/stroke inspect position/speed and global limits. Global stroke affects relative position commands across modes. HAMP state responses can additionally include optional min and max for the HAMP-specific stroke.

GET/PUT /slider/stroke return result objects containing relative min/max in [0,1] and device-specific min_absolute/max_absolute in millimeters. Both request fields are required. GET /slider/state reports position relative to that global range and position_absolute in millimeters.

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.

SliderState.position uses the current global stroke frame: (position_absolute - min_absolute) / (max_absolute - min_absolute). Use the current stroke when interpreting relative readings; changing limits can change the relative value without physical movement.

HVP: Vibration

Purpose: vibration and slider oscillation control on supported hardware. Use the compatibility matrix for model availability; a physical slider alone is insufficient. Authenticate and address the device.

Sequence: PUT /hvp/start → PUT /hvp/state → PUT /hvp/stop. Start sets amplitude to the default 0.3 (30%), replacing the previous amplitude, and preserves the current frequency. Inspect the returned state, then set desired parameters. Use GET /hvp/state for state monitoring.

Check HVP support for the target device and firmware. A slider capability alone does not establish HVP support. Inspect the API error envelope even when HTTP status is 200.

/hvp/state field Type Required Range or applicability
amplitude number Yes [0,1]; required for Handy and Oh.
frequency integer Yes [0,10000] Hz; required for Handy and Oh.
position number For supported Handy slider devices Relative floating-point value [0,1], inclusive, representing 0–100%; sets the point of oscillation on Handy 2 Pro.

position is relative: 0.5 represents 50%. Always supply it when using HVP on a supported Handy slider device; there is no documented default. Field requirements do not imply that unsupported models provide HVP.

Use the required fields for the target device:

Device Required request fields
Handy Pro variants (H02_pro, H02_1_pro) amplitude, frequency, position.
Oh vibrator amplitude, frequency; position is not required.

For slider devices, position controls the point of oscillation. Use the device-specific required fields above. The OpenAPI schema's standard required list contains the common fields amplitude and frequency; its x-required-by-device mapping lists all required fields for each device family. Generic OpenAPI validators do not enforce this extension. The device is addressed outside the JSON body, so callers must additionally enforce the Handy requirement for position using the known device type. For Oh, send amplitude and frequency without position.

HDSP: Immediate movements

Purpose: individual movements without script setup, buffering, or built-in clock synchronization. Authenticate and use the addressing declared per operation in the index.

Method and path Required movement fields Meaning
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 time.
PUT /hdsp/xpt xp, t Relative position and time.

Commands are forwarded immediately on a best-effort basis. For continued movement, send a sequence of commands. Prefer HSP or STREAM when synchronization with an external timeline is required.

Client timing responsibility: HDSP is not synchronized. The client must account for end-to-end command delivery delay through the API server to the device, including variation in that delay. For predictable game or application events, predict the required movement and dispatch the command ahead of the intended movement time. Sending at the event time introduces delivery delay before movement can begin. Early dispatch compensates for estimated latency; it does not schedule execution or guarantee exact timing.

Optional flag Type Default Meaning
stop_on_target boolean false If true, stop the slider when the target is reached.
immediate_rsp boolean false If true, return without waiting for the device response.

An immediate response does not confirm completed movement. Absolute limits depend on the hardware. HDSP xp accepts a fraction in [0,1], inclusive, for relative slider position. vp uses [0,1] as a fraction of the configured speed range: x_min_speed + vp * (x_max_speed - x_min_speed), using GET /settings/slider. Zero selects the minimum movement speed; use explicit stop control to halt movement. For PUT /hdsp/xpvp, this body requests the midpoint with vp=0.2:

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

For PUT /hdsp/xpt, the required fields are xp and t. This body requests the midpoint over 1000 milliseconds:

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

The XPT request requires xp and t. Inspect hdsp_state_changed events as available.

HSSP: Predetermined scripts

Purpose: preserve the v2-style URL-based script setup flow in v3. For most new script playback integrations, prefer the Stream API plus STREAM. Prerequisites: compatible device, authentication, addressing, a script URL retrievable by the Handy API server, and clock synchronization.

The setup body below uses the recommended demo pair. Use that pair's video for media synchronization; other frame rates, encodings and side-by-side variants are listed on the same page.

First-connection order: connection/firmware checks → script selection or hosting → HSSP setup → playback controls. PUT /hssp/stop and GET /hssp/state require that setup too; neither belongs before setup as an unconditional connection check. After setup, the application chooses when to send Play and whether to follow media play/pause. Waiting while media is paused is a common default, not an API requirement. See Connection and session preparation.

HSSP state responses, including pause and resume, contain result: HspState. Stop retains the prepared script and buffered points. Use HSSP controls for this managed session; direct HSP flush is not a cleanup operation for an HSSP-managed stream.

HSSP runs over HSP in the API and backend. GET /mode therefore reports HSP mode 4 for both protocols; mode 1 is reserved for future use. Do not reject a prepared HSSP session because its device reports mode 4.

Game use case: use short scripts as reusable motion sprites in games or similar interactive applications. Trigger the prepared movement sequence on an application event; after setup, replay it with PUT /hssp/play and start_time=0 rather than generating individual points in the client. Standalone effects can omit server_time; effects synchronized to an external timeline should supply a fresh estimate. This does not guarantee immediate playback or remove the setup and buffer-refill latency described below.

A single script may contain multiple patterns. Maintain a lookup from each pattern to its starting timestamp in milliseconds, then select it with start_time; for example, start_time=3000 selects a pattern beginning at 3 seconds. Author idle gaps between patterns, holding a common resting position through each gap, so the client has time to send PUT /hssp/stop before the next pattern starts. Account for scheduling and request-delivery delay when choosing gap lengths. Gaps do not automatically stop playback; the client remains responsible for stop or selection of another pattern.

In HSSP v3, the API server downloads the script at least once. The script URL must therefore be accessible to that server; a private-network-only host is unsupported even if the device can reach it. HSSP v2 downloaded the script on the device, which could share a private network with the script host. Do not assume that v2 network arrangement works in v3. For temporary public hosting, use the Hosting API v2 and pass its returned download URL to /hssp/setup.

HSSP caches scripts to try to speed up setup. Cache matching may use an ETag or a stable check specific to the hosting service. If no suitable check identifies the script, the server may download it and compare its hash. Do not assume a repeated URL avoids downloading or guarantees a cache hit.

A setup URL can supply a script token. When the server recognizes the downloaded file as a token, it resolves the associated script and checks token validity and intended-device authorization. Only after those checks pass does the server deliver the actual movement data; the device does not resolve the token carrier. A valid token-file upload to Hosting returns a token URL, not an ordinary hash-addressed script URL. Pass the returned URL unchanged.

  1. PUT /hssp/setup (hsspSetup): supply a script URL. The server fetches the script; private network URLs are unsupported.
  2. PUT /hssp/play (hsspPlay): supply required start_time in milliseconds and, for media synchronization, a fresh server_time estimate sampled at the same instant as that media position.
  3. During playback, use PUT /hssp/synctime (setHsspTime) with required current_time and a fresh server_time estimate for the same sampling instant to adjust media synchronization.
  4. PUT /hssp/stop (hsspStop): stop playback and movement.

Setup body (replace the URL with your own reachable script):

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

Play body with a server-time estimate, the recommended default for media-synchronized HSSP integrations:

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

Replace the illustrative timestamp with a fresh integer estimate from the chosen clock estimator. Sample the media position and server-time estimate for the same instant.

After awaited preparation, identity or status checks, resample the latest valid media position/rate and a fresh server-time estimate before constructing Play or Synctime. Distinguish normal advancing timestamps from a changed playback intent. A periodic heartbeat replacing a sample object does not by itself cancel the pending Play; requiring the same object after every awaited check can prevent playback whenever heartbeat timing overlaps the request. Validate the latest target/video, play/pause/seek/rate intent and operation generation instead, and discard superseded work after Stop, disconnect or a new intent. Serialize device writes and coalesce updates so obsolete commands cannot follow the latest choice. These are client scheduling recommendations, not additional API fields.

For standalone script playback without synchronization to media or another external timeline, omit server_time if no client estimate is needed.

Field Required Type/default
Setup url Yes in the operation's URL variant string, publicly reachable supported script.
Setup notify No boolean, false; opt in to HSP events over SSE for client monitoring, such as a playback-state UI. Not required for playback.
Play start_time Yes integer milliseconds relative to script start.
Play server_time No integer estimated server milliseconds; supply for media synchronization. Omission uses the server's current time.
Play playback_rate No number, 1.0; 0.5 half speed, 2.0 double speed.
Play loop No boolean, false.

PUT /hssp/setup accepts a script URL only, through HsspSetupUrl. Script formats and hosting are external dependencies.

HSSP handles threshold notifications and device data delivery on the server. HSSP clients do not need to implement the direct HSP event-driven refill workflow for playback to work. Enable notify=true only when the client wants HSP events for observation; this does not transfer buffer replenishment to the client. Optional monitoring includes GET /hssp/state, HSP events when enabled, and the described stream_end_reached event.

Pause/resume are PUT /hssp/pause and PUT /hssp/resume; both HSSP and HSP use the resume field pick_up. Its default is false: resume from the paused position; true picks up the current live position.

For media-event deduplication and paused seeks, use the acknowledged-state and desired-intent bookkeeping in Connection and session preparation.

Pause retains the playback clock and permits either resume or play afterward. Stop discards the clock; only play can restart playback after stop. Use pick_up=true to pause device movement while media continues, then catch up to the media's current action on resume. A client emulating this with stop/play must track the stream timestamp and elapsed time itself, as described in the HSP control guidance below.

Use the synctime filter strategy as client guidance: first request after two seconds with filter=0.9, then requests every ten seconds with filter=0.5. Restart the initial correction and request timer after every playback change, including play, seek, skip, or resume. Use HSSP endpoints throughout this workflow; the exact intervals and filter values are not API requirements.

HSSP v2 required the complete script on the device before playback, so the device buffer imposed a maximum script size. HSSP v3 is a layer on top of HSP: the server streams points into the device buffer and refills or replaces buffered points when needed. This includes scripts larger than the buffer and seeks to positions outside the buffered range. There is no whole-script size cap imposed by the device buffer in this streaming model.

Device buffer capacities:

Device Buffer capacity
Handy 2 series Up to 200,000 points; use the max_points returned by setup for the connected device.
Handy 1 Approximately 1,000–4,000 points, depending on the device configuration. Exact per-mode values are not specified here.

Handy 2 can usually hold the entire script, allowing all points to be pushed during HSSP setup; when the script fits, additional data delivery during playback is unlikely. Handy 1's smaller buffer makes server-managed refills more relevant for longer scripts. Capacity remains session-specific; inspect returned max_points rather than hardcoding a device capacity.

Seeking outside buffered points may add a server/device round trip while the server supplies the required range. For applications that jump among known motion patterns exceeding the buffer, split scripts or use HSP for explicit buffer control.

Backend HSSP setup

A provider's application backend can check entitlement and call PUT /hssp/setup with the source URL, keeping that URL and the raw script out of the client download flow. After acknowledged setup, the client or backend may use HSSP playback controls. The URL must remain reachable by the Handy API server. Setup and device controls still require a Handy REST Application ID or client token plus device addressing; an Authentication Key does not authorize them. This is a delivery architecture, not script-token issuance. See provider-managed playback for access-policy boundaries and the STREAM alternative.

HSP: Dynamic points and buffer control

Purpose: direct play or synchronized dynamic data with direct control of the device buffer. Prerequisites: compatible device, authentication, a device connection key for buffer/play operations, and the device clock setup described in clock synchronization. A client server-time estimate is optional.

For file-driven testing, use the demo video/script pairs. Convert funscript actions from {at,pos} to HSP points {t,x} in the client; preserve the millisecond timestamps and integer positions. A funscript URL is not itself an HSP points request.

Point generation follows point density and device limits:

  • Use the fewest points that describe the intended motion. Simple strokes usually need peaks, valleys, start/end points and holds; the device moves between points.
  • Add intermediate points when they meaningfully shape acceleration, deceleration or smoothness. Points along an already straight transition add no movement information and consume buffer space and data traffic.
  • Maximum speed, acceleration and reversal capability depend on the device model. The device tries to reach each position at its timestamp; when a movement cannot finish in time, it may reverse before reaching the target, shortening the stroke, or skip points to maintain the timeline. More points do not overcome physical limits.
  • Firmware settings can adjust some behavior. Account for the pattern's points and timing, the model and the firmware configuration when assessing the resulting movement.

For continuous HSP data, the client owns buffer replenishment and must handle threshold and starving notifications to avoid playback interruptions. Subscribe through SSE before playback; include the relevant HSP event names when using an event filter. HSSP handles these notifications and refill requests on the server.

For continuous output, prepare an initial transmitted horizon before Play or in its embedded add. Track the last acknowledged point timestamp and absolute stream index separately from generated/preview lookahead. Rendering must not consume or advance the device transmit queue. Snapshot or isolate the intended initial batch across asynchronous setup, and size it from the returned capacity; after acknowledgment, refill from the acknowledged horizon. One point remains a valid request, but is insufficient to describe an oscillating pattern. A future timestamp alone does not establish that preceding movement was delivered. Choose lookahead within the actual session capacity and delivery latency.

Complete HSP setup before any other HSP operation, including Stop and state inspection. A connection check does not prepare this session. After setup, use the flow below to supply points and control playback.

  1. PUT /hsp/setup (hspSetup): fully reset the HSP session, including playback settings. Optional integer stream_id has range [1,4294967295]; omit it unless your application needs to select an ID. Inspect returned max_points instead of assuming a fixed capacity.
  2. PUT /hsp/add (hspAdd): append points and set their overall stream index. Point x accepts integers [0,100], inclusive; this example uses positions 10 and 40:

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

The two points have absolute stream indexes 0 and 1. Point t is integer milliseconds relative to stream start; x is an integer position. The tail is the absolute index of the last point in the device buffer, using zero-based indexing.

  1. PUT /hsp/play (hspPlay): required start_time; optional server_time defaults to the server's current time.

json {"start_time":0,"playback_rate":1.0,"loop":false,"pause_on_starving":true}

Add a fresh server_time estimate for more accurate external synchronization. Optional add embeds an HspAdd request before play.

  1. Replenish the buffer using threshold notifications; stop with PUT /hsp/stop (hspStop).
HspAdd field Required Contract
points Yes Array of {t,x} objects; at most 100 points per request.
tail_point_stream_index Yes Absolute index within the whole stream of the last point in the device buffer; zero-based, minimum 0.
flush No boolean, false; true removes existing points before adding, preserving the existing playback clock. Replacement timestamps stay on that timeline.
tail_point_threshold No Integer at least 0; absolute stream-index notification threshold, applied after adding points. Use a positive value for refill notifications.

The device ignores threshold updates whose target index has already passed when the update arrives. During playback, choose a target sufficiently ahead to cover request delivery and processing time as well as later refill time.

Use a positive threshold with enough lead time for event delivery and refill. Zero is not a guaranteed event-on-start mechanism. Treat notifications as refill signals rather than exact scheduling instants.

Capacity is fixed within the session but may change at the next setup. Adding beyond remaining capacity evicts the oldest buffered points even if they are unplayed. Plan each refill so removed points have already played or are intentionally being replaced. Distinguish these state fields:

State field Meaning
stream_id Current HSP session identifier.
max_points, points Session capacity and stored point count. Played points can remain buffered; points is not the number still to play.
current_point Zero-based buffer index of the next target point. current_point == points means no further buffered target is available.
current_time Live playback clock in milliseconds relative to stream start, captured when the state snapshot was generated. Advances continuously while playing; not the last point's timestamp.
first_point_time, last_point_time Timestamp boundaries of buffered data.
tail_point_stream_index Last point's index in the overall stream, not the local buffer.
tail_point_stream_index_threshold Threshold returned in state; request field is tail_point_threshold.

The current_point definition above. It is relative to the device buffer, distinct from the absolute tail_point_stream_index within the whole stream. A value equal to the stored point count indicates no next target, not an empty buffer; played data can remain stored.

HspPlayState values: 0 not initialized, 1 playing, 2 stopped, 3 paused, 4 starving. GET /hsp/state returns state. PUT /hsp/threshold requires {"tail_point_threshold":5000}; this updates the threshold independently of adding points. PUT /hsp/flush clears the buffer.

Use the notifications as a refill and recovery workflow:

Event Condition Client action
hsp_threshold_reached Configured point threshold reached. Append the next points with PUT /hsp/add before starvation.
hsp_starving No playable data, regardless of pause_on_starving. Supply missing data and recover from starvation.
hsp_paused_on_starving With pause_on_starving=true, playback pauses and stream time is held; the device clock continues. This event is additional to hsp_starving. Supply more playable points.
hsp_resumed_on_not_starving Playable data is available and playback resumes after starvation; pause_on_starving=true. Observe recovery and continue replenishment.

Use flush=false for ordinary append/refill requests. Set a correct tail_point_stream_index for the last point in the overall stream and a sensible tail_point_threshold for refill notification. The index is not the buffer occupancy or a local buffer offset. Keep both values consistent when adding or replacing points and before play or resume. Play can carry them inside add; /hsp/threshold updates the threshold separately. Choose a threshold that gives the client enough time to receive the notification and deliver points before starvation. The returned state names that threshold tail_point_stream_index_threshold.

PUT /hsp/add with flush=true replaces buffered points without restarting the playback clock. Keep replacement timestamps relative to the existing stream; a new Play is not required merely because the buffer was replaced. Use Play when deliberately choosing a new playback start position or timing reference.

For explicit timing re-anchoring during a live pattern selection, send PUT /hsp/play with embedded add.flush:true. Generate replacement points at and ahead of the current shared pattern clock, keep the absolute tail fields consistent, and sample start_time (that current pattern position) and a fresh server_time estimate for the same instant. Preserve the pattern/media time origin; a new Play does not imply start_time:0 or a phase restart. No new setup is needed for the prepared session. For a continuous live timeline use loop:false, append ordinary refills with flush:false, and choose the starvation policy appropriate to the external or held clock. This is an explicit timing-reference alternative to queue-only Add replacement.

/hsp/resume currently accepts only pick_up; it has no tail fields or embedded add. Prepare points and tail metadata through /hsp/add and /hsp/threshold before resuming.

Use hsp_state_changed to observe state and hsp_looping for loop restarts. Include hsp_paused_on_starving and hsp_resumed_on_not_starving when generating event allowlists. Pause-on-starving controls timeline behavior during a shortage and does not remove the client's refill responsibility.

hsp_starving is emitted for either flag setting. It reports a recoverable shortage of playable points; it does not itself stop the session or require a new Play. For continuous streaming, supply playable points and observe recovery. An application may choose Stop, but Stop discards the playback clock and requires a new Play.

With pause_on_starving=false, logical stream time continues during starvation. Points whose timestamps are already in the past when processed are skipped; refills must include points ahead of the current stream time. Adding playable future points allows playback to continue on the existing clock.

With pause_on_starving=true, starvation pauses playback and holds logical stream time; the underlying device clock continues running. New playable data automatically resumes playback from the held stream time. Refill timestamps strictly greater than the last buffered point's timestamp (t > last_point_time) remain valid without retiming for the starvation period. The wall-clock wait does not age those points past the held stream position; points already behind that position are still past.

PUT /hsp/pause pauses playback. PUT /hsp/resume accepts optional boolean pick_up, default false: resume from the paused position; true picks up the live position. PUT /hsp/pause/onstarving requires boolean pause_on_starving; true pauses playback and holds stream time while playable points are unavailable, then automatically resumes from that time when data arrives. The device clock continues running. The initial play flag defaults to false.

HSP pause/resume responses contain result: HspState. Inspect play_state and current_point to identify paused playback; do not assume the reported clock snapshot is a frozen timestamp.

Control Documented behavior
/hsp/play Start at the explicitly supplied start_time; valid after stop or pause. An embedded add runs before play.
/hsp/pause Suspend playback and retain the playback clock and paused position. Either resume or play can follow.
/hsp/resume Continue paused playback from the paused position (pick_up=false, default) or the current live position (pick_up=true).
/hsp/stop Stop playback and device movement, discarding the playback clock. Only play can restart playback; resume is invalid after stop.

Play selects a start position explicitly; resume selects the retained paused or live position through its flag. A concrete use case is pausing device movement while media keeps playing, then resuming with pick_up=true to catch up to the current action. With false, movement continues from the paused position. Both HSP and HSSP use pick_up for this choice.

To emulate resume after stop, the client must record the stream timestamp at stop. Play from that saved timestamp for paused-position behavior. At playback rate 1.0, play from saved_timestamp + elapsed_since_stop for catch-up behavior; both values are milliseconds. Stop retains no playback clock for the server to calculate this automatically. /hsp/flush explicitly clears buffered points. Do not infer buffer clearing or session disposal from clock behavior alone.

PUT /hsp/synctime requires current_time, with optional server_time and filter. Omitted server_time uses the server's current time. Use the synctime filter strategy as application guidance if appropriate. PUT /hsp/loop requires loop; PUT /hsp/playbackrate requires playback_rate. Preserve its actual operation identifier setHspPaybackRate when using Swagger links or generated clients.

Direct play and replacement patterns

HSP supports direct play similar to HDSP. In an initialized HSP session, send PUT /hsp/play with start_time=0 and an embedded add request whose first point has t=0 and whose flush is true. Omit server_time; the server uses its current time. The embedded add clears and replaces buffered points before play, and playback begins as soon as possible. Point timestamps remain milliseconds relative to stream start; later points retain their relative timing.

Set loop=true to repeat the supplied pattern. Send another play request with replacement points and the same start, flush, and loop settings to change the repeating pattern. Omitted loop defaults to false for a single pass. Omitting server_time does not discard point timing or make the entire buffer play immediately.

STREAM: Stored scripts and live data

Purpose: synchronized stored-script playback or live data, with delivery handled by the server. Preferred for most new script playback integrations. Prerequisites: compatible device, authentication, addressing, clock synchronization, and an accessible stream_ref from the separate Stream API.

For test content, import a demo funscript URL through Stream API content.url, then use its returned stream_ref. Do not pass the video URL or funscript URL as a stream reference.

Device support: all device models support STREAM, subject to the firmware requirements. Oh translates movement into vibration.

Complete PUT /stream/setup before other STREAM playback or state operations, including Stop. Creating content through the separate Stream API does not initialize the device's Handy REST playback session.

Keep the authentication contexts separate:

Operation context Credential
Handy REST /stream/setup, /stream/play, /stream/state, /stream/synctime, /stream/stop Handy REST Application ID or device client token, plus device addressing.
Stream API POST /streams Separate Stream API Application ID in X-Api-Key. Stream client-token issuance is planned.
Stream API append-data endpoint Created stream's data_key.
Stream API editor endpoints, including close Created stream's editor_key.

Do not reuse a Handy REST token for Stream API creation. The returned stream_ref addresses content for device setup; it is not the Stream API creation credential.

Use the Stream API v0 to store script data on the servers and retain the returned stream_ref for subsequent setup requests. Reuse can make setup faster by avoiding repeated HSSP URL identification and possible download/hash checks. Its creation, append, metadata, and finalization operations use separate credential roles and are outside this Handy REST specification.

  1. Store script data or create/populate live data through the Stream API, or obtain an existing accessible stream reference.
  2. PUT /stream/setup (setupStream) requires string stream_ref; optional boolean notify defaults to false.

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

  1. PUT /stream/play (streamPlay) requires integer start_time in milliseconds. Optional server_time defaults to the server's current time. Optional playback_rate, loop, and pause_on_starving default to 1.0, false, and false respectively.

json {"start_time":0,"playback_rate":1.0,"loop":false,"pause_on_starving":true}

  1. Adjust timing with PUT /stream/synctime (setStreamTime), supplying required current_time and optional server_time and filter; stop with PUT /stream/stop (streamStop). Supply a fresh server_time estimate for more accurate external synchronization.

Setup resets existing HSP state and returns HspState. Inspect GET /stream/state; HSP SSE notifications require notify=true. stream_end_reached signals reaching the end of a closed stream. STREAM manages data delivery; client code need not implement HSP buffer replenishment. The same accessible stream can be used by multiple devices. Use the separate Stream API to store scripts, append data, close streams, administer streams, and control access.

Provider-owned streams

The provider's backend can import script content through the Stream API and retain its data/editor keys. Give the client only stream_ref for device setup, or perform PUT /stream/setup on the backend after checking entitlement and keep the reference there too. The client need not download the source script or receive its URL. After setup succeeds, the client or backend can send STREAM controls using Handy REST credentials and device addressing. Stream references and backend setup do not automatically supply script-token device binding, expiry or revocation; see the shared comparison.

HRPP: Repeating patterns

Purpose: play patterns available on the device. Authenticate and supply a device reference.

Device support: all device models support HRPP, subject to the firmware requirements. File types are audio and script. Oh supports both; Handy devices support script only. Select a pattern with a supported file type before activation.

  1. GET /hrpp/patterns (getHrppPatterns): inspect result.patterns and its slot values. The result is an object with state and patterns.
  2. PUT /hrpp/patterns/{slotNo}/activate (activateHrppPattern): use an actual returned slot; path parameter slotNo is an integer at least 0.
  3. PUT /hrpp/start (startHrpp): start playback.
  4. Adjust with PUT /hrpp/playbackrate and PUT /hrpp/amplitude.
  5. PUT /hrpp/stop (stopHrpp): stop playback.

/hrpp/playbackrate requires numeric playback_rate; 1.0 is normal speed. /hrpp/amplitude requires numeric amplitude, described as [0,1]. Neither schema declares a default; do not invent one. Inspect GET /hrpp/state or the described hrpp_state_changed event. The backend returns the pattern identifier as id. HrppPattern requires id. Activation uses the returned pattern slot.

State fields include nr_of_patterns and playback_rate. HrppPatternCatalogue contains required state: HrppState and patterns: HrppPattern[]. Activate a pattern using its returned slot; do not substitute current_pattern_nr or id for that slot.

SSE events

Purpose: receive device updates without repeated polling. Prerequisites: supported firmware, Application ID or client token, and a device connection key or channel reference. Swagger UI cannot exercise the SSE stream.

GET /sse accepts two device-addressing forms:

Address transport Value Client usage
Query parameter ck Device connection key or channel reference Primary form for native browser EventSource; also usable by non-browser clients.
Header X-Connection-Key Device connection key or channel reference Supported by the backend; usable by clients that expose custom HTTP headers.

The endpoint uses query parameter apikey for an Application ID or client token, with optional comma-separated events.

Supply at least one address parameter: ck or X-Connection-Key. GET /sse records this requirement in its x-required-any-of-parameters extension. Standard OpenAPI validators do not enforce that cross-parameter choice; callers must enforce it explicitly.

The HTML standard defines the native browser EventSource constructor with a URL and an options dictionary containing only withCredentials. MDN documents the same interface. There is no custom-header option. withCredentials controls the request's credentials mode; it does not let application code set X-Connection-Key or arbitrary authentication headers. This browser API limitation does not prohibit other SSE clients from sending custom headers.

Primary browser URL example:

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

URL-encode actual values. Do not put an Authentication Key in browser code. This is an illustrative client example.

Event group Event names
Connection device_status, device_connected, device_disconnected
Timing and modes device_clock_synchronized, mode_changed
Protocol state hamp_state_changed, hdsp_state_changed, hvp_state_changed, hrpp_state_changed, hsp_state_changed
Buffered playback hsp_threshold_reached, hsp_starving, hsp_looping, stream_end_reached
Pause-on-starving hsp_paused_on_starving, hsp_resumed_on_not_starving
Physical input button_event for unhandled input only
Device conditions device_error, low_memory_warning, low_memory_error, slider_blocked, slider_unblocked, temp_high, temp_ok

When filtering a subscription, include device_status if your browser waits for EventSource open before starting protocol activity. It supplies an initial event without waiting for a later mode or playback change. A filter containing only future events can remain quiet. The initial status contains connection and device information, not the active mode or protocol state.

For the complete event list, use #/components/schemas/SSEEventType in the OpenAPI specification. SSEEvent models id, type, and data; SSEEventData requires connection_key and may contain event-specific data.

SSE frames contain separate id:, event:, and JSON data: fields. The JSON body contains {connection_key, data}. Assemble SSEEvent.id and SSEEvent.type from the wire fields; do not expect them inside the JSON body.

Treat unexpected EOF and transport/parse errors as failures, while allowing quiet event intervals. Receiving SSE does not establish device reachability. If a stop request is not acknowledged, restore access and read device state before further movement commands.

Dispatch by documented event name. If a name is absent from the supported specification, check that the client uses the current specification and report any remaining mismatch as a possible API or specification bug.

Handle disconnection explicitly and reconcile device state after reconnecting. Renew a client token before expiry and recreate the connection when credentials change. Do not rely on event replay or Last-Event-ID to recover missed events. See the SSE example source and EventSource reference for implementation examples.

Physical buttons and device modes

Scope: firmware v4+. button_event reports unhandled input. A mode may consume physical input to adjust settings; handled input is not also forwarded as raw button_event. Different press/release/short/long-press stages may be handled differently. Power/Wi-Fi actions may be device-wide. Button behavior depends on the device 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.

Available modes and protocol support depend on the device and firmware. STREAM is a playback API feature and HSTP a clock-synchronization protocol; neither is another mode value. Use the reported mode rather than deriving button behavior from an API feature name.

For diagnosis, omit the events filter and compare state before/after each physical input stage. stroke_changed, hamp_state_changed, and hsp_state_changed are candidate resulting notifications, not per-press guarantees. Repeating a setting may emit no change. A button_event-only filter excludes state notifications; an absent raw event alone does not establish an SSE delivery defect.

ButtonEvent is event-specific data with required integer fields:

Field Enum values
button 0 POWER, 1 UP, 2 LEFT, 3 RIGHT, 4 DOWN, 5 WIFI.
event 0 PRESSED, 1 RELEASED, 2 SHORT_PRESS, 3 LONG_PRESS_START, 4 LONG_PRESS_STEP, 5 LONG_PRESS_END.

{"button":2,"event":2} denotes a forwarded left-button short press. The active mode determines which physical inputs are forwarded.

Errors, timeouts, and rate limits

Response handling

Many device operations return HTTP 200 with either result or error. Check HTTP status, decode JSON where applicable, and inspect error before treating the operation as successful. Not every success returns data. GET /servertime uses a top-level server_time, not result.

Decode success according to the selected operation, rather than requiring one response shape everywhere:

Operation Representative success body
GET /connected {"result":{"connected":true}}
GET /servertime {"server_time":1760000000000}
PUT /hdsp/xpt {"result":"ok"}

The server-time value is illustrative. Error handling runs before success decoding, including for HTTP 200. Use each operation's declared schema for object, scalar, array or absent success data; a missing result alone is not a universal failure test. Hosting and Stream API operations have their own response contracts.

error.data may be an object or a string, including "". Check its type before accessing nested properties.

Example device error:

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

All errors share required code and name fields and optional message and data fields. DeviceError additionally requires connected to report the device's connection status; GenericError, used by token operations, does not require it. Handle absent message and data fields. DeviceNotConnected has example code 1001; DeviceTimeout has example code 1002. Do not require connected on every API error.

Shared response definitions describe HTTP 400 bad request, 401 unauthorized, 403 forbidden, 404 not found, 408 request timeout, 429 too many requests, and 500 internal error. Individual operations do not enumerate every shared response. A timeout does not establish whether a movement command was applied; reconcile state before deciding whether to retry.

Stop and lifecycle recovery

Keep explicit Stop available while output is enabled and check its acknowledgment. A page-exit request is best effort: closing a tab, losing network access or terminating the browser can prevent delivery. Report an unconfirmed Stop and direct the user to the device controls instead of claiming output has stopped.

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, reconcile the known prepared session before retrying; automatic replay may repeat a movement that already executed. Preserve setup prerequisites during recovery. Protocol state queries and Stop still require their matching setup, and setup itself replaces the session rather than inspecting it.

Timeout and quota fields

Field Unit Meaning
Query timeout milliseconds Integer; default/minimum 5000, maximum 60000, where declared.
X-RateLimit-Limit requests Limit per minute window.
X-RateLimit-Remaining requests Requests left in the current window.
X-RateLimit-Reset seconds Seconds until the next window reset, not an epoch timestamp.

Read returned quota headers; example values such as 240 are not guaranteed account limits. Suggested application behavior: reduce requests as remaining quota approaches zero and use returned reset information for scheduling after throttling. HTTP timeout and device timeout are distinct error paths. The index identifies operations but does not imply every one supports timeout; consult its OpenAPI parameter list.

Endpoint index

Use the exact method, path, and operation identifier shown below. Device/channel means a device connection key or channel reference; Device means a connection key only. Most operations use X-Connection-Key; SSE also accepts query parameter ck.

Body fields list required request fields; conditional HVP requirements are noted separately. They do not describe every optional field, whether a request body itself is mandatory, or all validation constraints. For full contracts, locate the method under paths in the OpenAPI specification, including its documented extensions. slotNo is a separate required path parameter for pattern activation.

Method and path operationId Authentication Address Required body fields
GET /auth/token/issue issueToken Authentication Key (bearer) None No body defined
GET /hrpp/state getHrppState Application ID or client token Device/channel No body defined
PUT /hrpp/start startHrpp Application ID or client token Device/channel No body defined
PUT /hrpp/stop stopHrpp Application ID or client token Device/channel No body defined
PUT /hrpp/playbackrate setHrppPlaybackRate Application ID or client token Device/channel playback_rate
PUT /hrpp/amplitude setHrppAmplitude Application ID or client token Device/channel amplitude
GET /hrpp/patterns getHrppPatterns Application ID or client token Device/channel No body defined
PUT /hrpp/patterns/{slotNo}/activate activateHrppPattern Application ID or client token Device/channel No body defined
GET /hamp/state getHampState Application ID or client token Device/channel No body defined
PUT /hamp/state setHampState Application ID or client token Device/channel No fields required
PUT /hamp/start startHamp Application ID or client token Device/channel No body defined
PUT /hamp/stop stopHamp Application ID or client token Device/channel No body defined
PUT /hamp/velocity setHampVelocity Application ID or client token Device/channel velocity
PUT /hamp/stroke setHampStroke Application ID or client token Device/channel min, max
GET /settings/slider getSliderSettings Application ID or client token Device/channel No body defined
GET /info getDeviceInfo Application ID or client token Device only No body defined
GET /mode getMode Application ID or client token Device/channel No body defined
PUT /mode setMode Application ID or client token Device/channel mode
PUT /mode2 setMode2 Application ID or client token Device/channel mode
GET /connected isConnected Application ID or client token Device/channel No body defined
GET /sse getEvents Application ID or client token (query apikey) Device/channel via ck or X-Connection-Key No body defined
GET /servertime getServerTime Public None No body defined
GET /statistics getStatistics Application ID or client token Device No body defined
GET /capabilities getDeviceCapabilities Application ID or client token Device No body defined
GET /sids getDeviceSessionIds Application ID or client token Device No body defined
PUT /hdsp/xava sendXava Application ID or client token Device xa, va
PUT /hdsp/xavp sendXavp Application ID or client token Device xa, vp
PUT /hdsp/xpva sendXpva Application ID or client token Device xp, va
PUT /hdsp/xpvp sendXpvp Application ID or client token Device xp, vp
PUT /hdsp/xat sendXat Application ID or client token Device xa, t
PUT /hdsp/xpt sendXpt Application ID or client token Device xp, t
GET /hssp/state getHsspState Application ID or client token Device/channel No body defined
PUT /hssp/setup hsspSetup Application ID or client token Device/channel url (URL variant only)
PUT /hssp/play hsspPlay Application ID or client token Device/channel start_time
PUT /hssp/stop hsspStop Application ID or client token Device/channel No body defined
PUT /hssp/pause hsspPause Application ID or client token Device No body defined
PUT /hssp/resume hsspResume Application ID or client token Device No fields required
PUT /hssp/synctime setHsspTime Application ID or client token Device/channel current_time
PUT /hsp/setup hspSetup Application ID or client token Device/channel No fields required
PUT /hsp/flush hspFlush Application ID or client token Device No body defined
PUT /hsp/add hspAdd Application ID or client token Device points, tail_point_stream_index
PUT /hsp/play hspPlay Application ID or client token Device start_time
PUT /hsp/stop hspStop Application ID or client token Device No body defined
GET /hsp/state getHspState Application ID or client token Device No body defined
PUT /hsp/threshold setHspThreshold Application ID or client token Device tail_point_threshold
PUT /hsp/pause hspPause Application ID or client token Device No body defined
PUT /hsp/resume hspResume Application ID or client token Device No fields required
PUT /hsp/pause/onstarving setHspPauseOnStarving Application ID or client token Device pause_on_starving
PUT /hsp/synctime setHspTime Application ID or client token Device current_time
PUT /hsp/loop setHspLoop Application ID or client token Device loop
PUT /hsp/playbackrate setHspPaybackRate Application ID or client token Device playback_rate
GET /hstp/info getDeviceTimeInfo Application ID or client token Device No body defined
GET /hstp/clocksync clockSync Application ID or client token Device No body defined
PUT /hstp/offset setOffset Application ID or client token Device offset
GET /hstp/offset getOffset Application ID or client token Device No body defined
GET /hvp/state getHvpState Application ID or client token Device No body defined
PUT /hvp/state setHvpState Application ID or client token Device amplitude, frequency; Handy additionally requires position
PUT /hvp/start hvpStart Application ID or client token Device No body defined
PUT /hvp/stop hvpStop Application ID or client token Device No body defined
GET /slider/state getSlideState Application ID or client token Device No body defined
PUT /slider/stroke setStroke Application ID or client token Device/channel min, max
GET /slider/stroke getStroke Application ID or client token Device/channel No body defined
PUT /stream/setup setupStream Application ID or client token Device/channel stream_ref
PUT /stream/play streamPlay Application ID or client token Device/channel start_time
PUT /stream/stop streamStop Application ID or client token Device/channel No body defined
GET /stream/state getStreamState Application ID or client token Device/channel No body defined
PUT /stream/synctime setStreamTime Application ID or client token Device/channel current_time

Glossary

Term Meaning
Device connection key Device address supplied separately from authentication.
Channel reference Address for a group managed through the separate Channel API.
Client token Expiring, optionally restricted API credential issued server-side.
stream_ref Stream API reference used by STREAM setup.
stream_id HSP session identifier; not a Stream API reference.
RTD Round-trip delay between participants, in milliseconds.
cs_offset Estimated server time minus client time.
Tcest Client estimate of server time from the selected estimator; averaging uses current client time plus cs_offset, while Kalman predicts offset and drift.
Buffer index Position within the points currently stored on the device.
Stream index Position in the overall point stream, independent of buffer replacement.
Starving Playback has no more playable points; behavior depends on pause-on-starving.

External dependencies

These services and script formats have separate references. Their contracts are outside the Handy REST specification: