Skip to content
Handyverse documentation

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

Open full Swagger UI
API documentation · The Handy Channel API v1View Markdown

Documentation 2026.11.15.1 · Tag docs-2026.11.15.1 · Version and checksums

The Handy Channel API v1: agent reference

Integration instructions for Channel API v1 (1.0.0-beta, OpenAPI 3.0.3). Production base URL: https://www.handyfeeling.com/api/channel/v1. The human guide explains the same workflow; the OpenAPI specification supplies the full schemas.

Purpose: multicast supported Handy REST commands to active subscribers and propagate control-state changes between paired devices. V1 also retains single-device alias behavior: when alias mode is enabled and the channel has exactly one subscriber, supported Handy REST requests return that device's actual response. The Channel API manages memberships; Handy REST carries commands.

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

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

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 and spec; 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 against the manifest's file checksum before using it with the guide. 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 Channel or device API operations.

Integration order

  1. Distinguish Channel API membership/lifecycle requests from Handy REST device commands.
  2. Choose the exact operation and credential below. Treat identifiers and access keys as different values.
  3. For device subscribers, check compatible firmware v4 and the selected protocol's hardware requirements. Follow the Handy REST firmware policy: UPDATE_REQUIRED blocks further device interaction and requires directing the participant to the updater. Only active subscribers receive forwarded data; channel state does not establish per-device compatibility.
  4. Create a channel, retain its returned identifiers/keys, and let participants join with their own device connection keys.
  5. Use chref:CHANNEL_REF only in supported Handy REST addressing fields, with Handy REST authentication. A multicast acknowledgement is not a per-device execution result.
  6. Execute requests only when the user task authorizes their effects. GET /subscriptions/close changes state.
  7. End active movement before closing its routing resources. Close the browser's SSE connection when finished.

Identifiers and authentication

Sign up and sign in at the user portal, then issue an Application ID (application_id) or Authentication Key (authentication_key) for Channel. If your account cannot issue credentials for an API, contact platform support about access to that API. See Developer access for shared signup and credential guidance. Keep Authentication Keys server-side. Select the credential and transport declared for the operation; a shared issuance portal does not replace endpoint-specific authentication requirements.

Credential or identifier Usage
API credential for channel creation POST /channels; X-Api-Key or query apikey.
User authentication credential GET /channels; X-Auth-Key.
Channel editor key (channel_key) Channel editor reads, updates, closure, subscriber lists and management; X-Api-Key or apikey.
Subscriber key (subscriber_key) POST /channels/{channelId}/subscribers; X-Api-Key or apikey.
Device connection key Subscriber body connection_key; GET /subscriptions and the explicit leave-all operation use header X-Connection-Key. Individual membership management requires the editor key.
Channel ID (channel_id) Channel API path identifier; also sufficient to open Channel lifecycle SSE.
Channel reference (channel_ref) Handy REST channel address, prefixed exactly once as chref:CHANNEL_REF.
Subscriber ID (subscriber_id) Membership identifier, used together with channel_id.

X-Api-Key and query apikey are alternative transports; supply one. Creation credentials, channel editor keys, and subscriber keys have different roles despite sharing these names. Never substitute a channel ID for a channel reference, or a join key for an editor key. Check the credential requirements independently when crossing into Handy REST.

No Channel client-token issuance operation is defined by v1. Do not substitute another API's token issuer.

Keep editor access restricted. Participants can join using channel_id, subscriber_key, and their own device key without giving the channel creator their device key. Knowing the channel reference permits addressing the group through supported Handy REST operations with the required REST credentials. Channel lifecycle SSE has no authentication requirement beyond knowing the channel ID.

Endpoint index

Paths are relative to the Channel API base URL. channelId and subscriberId are required string path parameters wherever present. Header/query editor and join credentials use X-Api-Key/apikey.

Method and path operationId Authentication Body / response
GET /channels getUserChannels User credential in X-Auth-Key Paginated {data: Channel[], ...Meta}; HTTP 200.
POST /channels createChannel API credential for channel creation Required NewChannel body; direct Channel, HTTP 200.
GET /channels/{channelId} getChannel Editor key Channel, HTTP 200.
PUT /channels/{channelId} updateChannel Editor key Required ChannelUpdate body; Channel, HTTP 200.
GET /channels/{channelId}/sse getEvents None SSE stream; optional events filter.
PUT /channels/{channelId}/close closeChannel Editor key Closes channel and remaining memberships; HTTP 200, empty body.
GET /channels/{channelId}/subscribers getSubscribers Editor key Paginated {result: {data: Subscriber[], ...Meta}}, HTTP 200.
POST /channels/{channelId}/subscribers createSubscriber Join key Required NewSubscriber body; direct Subscriber, HTTP 200.
GET /channels/{channelId}/subscribers/{subscriberId} getSubscriber Editor key Subscriber, HTTP 200.
PUT /channels/{channelId}/subscribers/{subscriberId} updateSubscriber Editor key Required SubscriberUpdate body; Subscriber, HTTP 200.
PUT /channels/{channelId}/subscribers/{subscriberId}/close closeSubscriber Editor key HTTP 200, empty body.
GET /subscriptions getSubscriptions Device connection key Direct Subscriber[], HTTP 200; device must be online.
GET /subscriptions/close closeSubscriptions Device connection key State-changing GET; closes all non-closed memberships for an online device; {closed: integer}, HTTP 200.

Request and response contracts

Request-body presence and required object fields are separate constraints. The four create/update operations require a JSON body. Use their schema's standard required list when generating clients; supply a device connection_key when creating a device membership.

  • NewChannel: optional name, description, and settings. Prefer meaningful human-readable name/description.
  • ChannelUpdate: optional name, description, and settings.
  • NewChannelSettings: offset (nonnegative integer, milliseconds, default 0, no currently enforced upper limit) and device_events (boolean, default false). Read device information with individual device keys; Channel v1 references do not support Handy REST GET /info.
  • NewSubscriber: required string connection_key plus optional settings. An empty object does not satisfy the creation schema.
  • SubscriberSettings (input): optional offset (nonnegative integer milliseconds), type, event_source, and hw_model_no. type defaults to session; event_source defaults false. On creation, an omitted offset dynamically follows the channel default; an explicit 0 means no delivery delay. Do not insert 0 for an omitted subscriber offset. Explicit -1 input is not supported.
  • SubscriberResponseSettings (output): the same settings fields, with offset: -1 representing dynamic inheritance. Explicit nonnegative offsets remain independent of later channel-default changes.
  • SubscriberUpdate: optional settings referencing SubscriberSettings; PUT returns the updated Subscriber, not a standalone settings object. device_events belongs to channel settings.
  • Subscriber delay update example: {"settings":{"offset":1500}} with PUT /channels/{channelId}/subscribers/{subscriberId}.

Creation returns channel_id, channel_ref, channel_key, and subscriber_key in a direct Channel object. Its required attributes include status, and shared entity fields created_at/updated_at. A Subscriber requires subscriber_id, channel_id, status, and the entity timestamps. These are not Handy REST result envelopes.

Channel metadata describes group state, not independent telemetry for each member. Its channel modes are HAMP 0 and HVP 8. Units match Handy REST v3:

Metadata field Unit / range
slide.min, slide.max Relative numbers [0,1], inclusive.
hamp.min, hamp.max Relative numbers [0,1] within the global slider range.
hamp.velocity Normalized number [0,1] within configured minimum/maximum speeds.
hvp.amplitude, hvp.position Relative numbers [0,1]; position applies to slider devices.
hvp.frequency Integer Hz [0,10000].

Use 0.5 for 50% of a relative range. Channel metadata uses these scales in returned channel objects and channel-state SSE payloads.

Pagination, filters, and errors

GET /channels defaults to active channels. GET /channels/{channelId}/subscribers defaults to non-closed subscribers. Both accept status as a comma-separated array, limit from 1 through 1000 (default 100), offset at least 0 (default 0), and cursor. A provided cursor overrides offset. List metadata can include count, offset, and the next cursor.

GET /channels puts data and pagination metadata at the top level. GET /channels/{channelId}/subscribers puts them under result. GET /subscriptions remains a direct array. Do not apply one envelope to all collection operations.

The pagination offset counts elements. Settings offset is a millisecond delivery delay; these meanings are unrelated.

GET /subscriptions returns a direct array and requires an online device to return memberships. Bulk closure also requires the device online. An empty offline lookup does not prove no memberships exist.

Check HTTP status and the endpoint-specific body. Channel/subscriber close operations return empty HTTP 200; do not JSON-decode them. Read the resource separately when its closed state is needed. The shared unauthorized/server-error schemas contain required message; do not assume a Handy REST error/result envelope. Inspect rate-limit headers when returned. Shared headers describe the per-minute limit, remaining requests, and milliseconds until reset; do not hard-code an example limit as an account guarantee.

Membership lifecycle and pairing

Subscriber type Closure conditions
session Device disconnect, explicit subscriber close, or channel close.
connection_key Device connection-key change, explicit subscriber close, or channel close.
device Explicit subscriber close or channel close.

Subscriber status is active, inactive, or closed. Only active members receive forwarded commands. Channel status is active or closed. Closing a channel prevents further commands and joins and closes remaining non-closed subscribers. Channels are automatically closed after no subscriber has been active for the preceding six hours.

An event_source=true subscriber contributes physical-button-initiated changes to stroke, speed, or vibration to the channel. Multiple subscribers can be sources; making each participant a source provides device pairing. This differs from channel device_events=true, which enables monitoring device events through Handy REST SSE.

Delivery delay

Channel offset supplies the current default; subscriber offset selects dynamic inheritance or an independent complete delivery delay. Omit the offset when creating a subscriber to follow the default. Responses/events represent inheritance as -1: changing a channel default from 1000 to 2000 changes that subscriber's delay to 2000 milliseconds. An explicit 500 remains 500; explicit 0 means no delay. Supply nonnegative whole milliseconds in create/update requests; -1 is only a response indicator in v1. No upper limit is currently enforced.

Use the movement protocol's clock synchronization when coordinating with media. A channel delivery offset alone is not an external-media synchronization guarantee.

Handy REST multicast operations

Channel compatibility is specific to each Handy REST method/path. Use its endpoint index and addressing schema before sending X-Connection-Key: chref:CHANNEL_REF, including for single-subscriber/alias routing. Supported calls use the Handy REST v3 base URL and its authentication. The summary includes /info as an explicit unsupported operation:

Area Methods and paths
Device information GET /info requires an individual device key; Channel v1 references return NOT_SUPPORTED (141008) inside HTTP 200.
Mode / connectivity GET /mode, PUT /mode2, GET /connected; legacy PUT /mode is deprecated.
HAMP — Handy Alternate Motion Protocol PUT /hamp/start, /hamp/stop, /hamp/velocity, /hamp/stroke; GET /hamp/state.
HVP — Handy Vibration Protocol PUT /hvp/state, /hvp/start, /hvp/stop; GET /hvp/state.
Slider stroke GET and PUT /slider/stroke.
Device events Handy REST GET /sse with a channel reference and channel device_events=true.

Preserve Handy REST's payload units and device-specific requirements. Do not infer support for every Handy REST endpoint. Normal multicast returns one channel-level response once forwarding is accepted, without waiting for every device acknowledgement. Ordinary group reads can report channel state; GET /connected reports channel openness. GET /info does not accept Channel v1 references; use individual device keys for firmware/hardware checks.

For /info addressed through a v1 channel reference, HTTP 200 contains {"error":{"code":141008,"name":"NOT_SUPPORTED","message":"Not supported","connected":true,"data":""}}. Inspect the response body for an operation error even when the HTTP status is 200; check other endpoints independently.

Single-device alias behavior

When v1 alias mode is enabled and the channel has exactly one subscriber, chref:CHANNEL_REF acts as an alias for that device. Supported Handy REST requests return the actual device response using the endpoint's normal response format. Keep this distinct from ordinary multicast acknowledgements. A single subscriber is the cardinality requirement; do not infer an undocumented activation parameter from the name “AliasMode.”

Alias routing does not imply support for all methods. GET /info with a v1 channel reference returns HTTP 200 containing NOT_SUPPORTED (141008), including with one subscriber.

Channel lifecycle SSE

GET /channels/{channelId}/sse is unauthenticated. A native browser EventSource needs only the URL. Optional comma-separated events selects event types; omission means all. Wire frames use id:, named event:, and JSON data: containing the event-specific payload directly. SSEEvent is a parsed representation with id, event, and data, not a JSON envelope sent by the server. Browser clients use event.type, event.lastEventId, and JSON.parse(event.data).

Event Data schema / purpose
channel_state ChannelStateData: channel ID and channel-state object; connection and state updates.
channel_closed ChannelClosedData: channel ID, closure timestamp, optional reason.
subscriber_added ChannelSubscriberAddedData: membership identity and settings.
subscriber_closed ChannelSubscriberClosedData: membership identity, closure timestamp, optional reason.
subscriber_inactive ChannelSubscriberInactiveData: persistent membership became inactive; IDs and optional returned-settings snapshot.
subscriber_activated ChannelSubscriberActivatedData: persistent membership became active again; IDs and optional returned-settings snapshot.

Handle named event types explicitly and close the client stream when its view/session ends. Fetch the current subscriber list separately: initial subscriber snapshots and settings-update notifications are not part of the v1 SSE flow. Use update responses or GET for current membership settings. Reconcile state through reads after reconnecting; do not assume replay guarantees.

The Handy REST SSE connection is separate: it uses Handy REST credentials plus channel addressing and carries device events when enabled. Channel lifecycle SSE does not require device_events=true and does not use a device connection key as its path identifier.

Finishing a control session

  1. End movement using the active Handy REST protocol's stop command while the channel can still forward it.
  2. Close the individual membership or whole channel as authorized.
  3. Use GET /subscriptions/close only for an explicit leave-all action; its GET method does not make it read-only.
  4. Close local event connections. Do not infer per-device stopped state from a multicast acknowledgement or from closing routing resources.