--- format_version: 1 api_id: "handy-rest-v3" api_version: "v3" docs_version: "2026.11.15.1" docs_tag: "docs-2026.11.15.1" docs_revision: "921fa2997bf166490f1bf8ffaae3176999813739948231f0072a11b73169f78d" source_revision: "02d17945187e6c91c4438aa8daa3e1b58e2cdcc8" body_sha256: "f4328407db7df9d95cebe1a0b9df52f9581ae0959ad8f185738dd5f7796baebf" updates: "https://links.handyfeeling.com/docs-handy-rest-api-v3-version" --- # 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](https://links.handyfeeling.com/docs-handy-rest-api-v3). Use the [API overview for agents](https://links.handyfeeling.com/docs-agent-index) 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](https://links.handyfeeling.com/spec-handy-rest-api-v3) | | Developer resources | [Documentation home](https://links.handyfeeling.com/docs-home), [Swagger UI](https://links.handyfeeling.com/swagger-handy-rest-api-v3) | 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](https://links.handyfeeling.com/spec-handy-rest-api-v3). 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](#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](https://links.handyfeeling.com/docs-guide-device-protocol-compatibility) for model availability, movement output and firmware requirements. Do not infer protocol support from physical slider count. The [human guide](https://links.handyfeeling.com/docs-handy-rest-api-v3) explains the same API. This reference supplies the complete operation index and integration requirements. ## Contents - [Compatibility](#compatibility) - [Quickstart](#quickstart) - [Authentication and device addressing](#authentication-and-device-addressing) - [Choosing a protocol](#choosing-a-protocol) - [Units and clock synchronization](#units-and-clock-synchronization) - [Protocol guides](#protocol-guides) - [SSE events](#sse-events) - [Errors, timeouts, and rate limits](#errors-timeouts-and-rate-limits) - [Endpoint index](#endpoint-index) - [Glossary](#glossary) - [External dependencies](#external-dependencies) ## 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](https://links.handyfeeling.com/docs-guide-device-protocol-compatibility) 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](https://handyverse.com/#/ota). 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](#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](https://user.handyfeeling.com/invite), then create an Application ID in the [user portal](https://user.handyfeeling.com). The account access token is for account management and is not an API credential. Replace the placeholders below. These commands only inspect the device. ```bash 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: ```json {"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](#errors-timeouts-and-rate-limits). ```bash 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](#compatibility). Then choose a [protocol](#choosing-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. ```javascript 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](https://links.handyfeeling.com/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](https://links.handyfeeling.com/docs-guide-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: ```http 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`): ```bash 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](#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](https://links.handyfeeling.com/docs-channel-api-v1-agents). SSE accepts either query parameter `ck` or header `X-Connection-Key`; consult [SSE events](#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](https://links.handyfeeling.com/docs-channel-api-v1-agents#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](https://links.handyfeeling.com/docs-guide-server-time-estimation) 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. ```bash 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](#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](#errors-timeouts-and-rate-limits). ### 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`). ```bash 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](https://links.handyfeeling.com/docs-guide-device-protocol-compatibility#protocol-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`: ```json {"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: ```json {"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](#stream-stored-scripts-and-live-data). Prerequisites: compatible device, authentication, addressing, a script URL retrievable by the Handy API server, and [clock synchronization](#units-and-clock-synchronization). The setup body below uses the recommended [demo pair](https://links.handyfeeling.com/docs-guide-demo-content#start-with-this-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](#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](https://links.handyfeeling.com/docs-hosting-api-v2-agents) 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](https://links.handyfeeling.com/docs-guide-script-tokens#a-token-as-a-file-or-url). 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): ```json {"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: ```json {"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](#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](#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](#tune-timing-corrections) 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](https://links.handyfeeling.com/docs-guide-script-tokens#offer-playback-without-a-script-download) 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](#units-and-clock-synchronization). A client server-time estimate is optional. For file-driven testing, use the [demo video/script pairs](https://links.handyfeeling.com/docs-guide-demo-content#choose-the-playback-flow). 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](https://links.handyfeeling.com/docs-guide-script-formats#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](#sse-events) 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. 3. `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. 4. 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](#tune-timing-corrections) 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](#units-and-clock-synchronization), and an accessible `stream_ref` from the separate Stream API. For test content, import a [demo funscript URL](https://links.handyfeeling.com/docs-guide-demo-content#choose-the-playback-flow) 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](https://links.handyfeeling.com/docs-guide-device-protocol-compatibility#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](https://links.handyfeeling.com/docs-stream-api-v0-agents) 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](#external-dependencies), 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} ``` 3. `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} ``` 4. 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](https://links.handyfeeling.com/docs-guide-script-tokens#offer-playback-without-a-script-download). ### 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](https://links.handyfeeling.com/docs-guide-device-protocol-compatibility#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](https://html.spec.whatwg.org/multipage/server-sent-events.html#the-eventsource-interface) defines the native browser `EventSource` constructor with a URL and an options dictionary containing only `withCredentials`. [MDN](https://developer.mozilla.org/en-US/docs/Web/API/EventSource/EventSource) 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: ```text 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](https://links.handyfeeling.com/spec-handy-rest-api-v3). `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](https://gitlab.com/sweettechas/platform/platform-api-examples/handy-rest-api-v3/sse) and [EventSource reference](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) 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: ```json {"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](https://links.handyfeeling.com/spec-handy-rest-api-v3), 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: - [Script formats](https://links.handyfeeling.com/docs-guide-script-formats): funscript JSON and Handy CSV. [Scripting](https://links.handyfeeling.com/docs-guide-scripting) covers authoring, review, and scripting tools. - [Scripting pipeline](https://links.handyfeeling.com/docs-guide-scripting-pipeline): partner SFTP onboarding and video identifiers. [Script tokens](https://links.handyfeeling.com/docs-guide-script-tokens) covers provider content-access options and Hosting playback handling; these are separate from API client-token authentication. - [Hosting API v2 agent reference](https://links.handyfeeling.com/docs-hosting-api-v2-agents) and [Swagger UI](https://links.handyfeeling.com/swagger-hosting-api-v2): temporary script hosting when your application has no public host. - [Stream API v0 agent reference](https://links.handyfeeling.com/docs-stream-api-v0-agents) and [Swagger UI](https://links.handyfeeling.com/swagger-stream-api-v0): stream creation, appending data, resource keys, and lifecycle. - [Platform API examples](https://gitlab.com/sweettechas/platform/platform-api-examples): externally maintained integration examples; check their API version before use.