Skip to content
Handyverse documentation

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

The Handy Channel API v1 request settings

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

The Handy Channel API v1

A channel lets you reach one or more devices through a single reference. Send a supported command once, and the channel forwards it to its active subscribers. This is multicast control. Use the Channel API to create the channel and manage its subscribers, then send commands through the Handy REST API v3, using the channel reference where a device connection key would normally go.

A channel also supports device pairing. When a subscriber is configured as an event source, changes made through its physical controls can propagate through the channel to the other active subscribers. Several devices can be event sources, allowing them to influence one another.

These features are useful for shared control sessions and live broadcasts. Start with a small channel and session-based subscribers. You can add pairing, persistence, and delivery delays once the basic flow is working.

Channel API v1 is the current public version. Device subscribers need compatible firmware v4. Its production base URL is:

https://www.handyfeeling.com/api/channel/v1

Apply the device firmware policy to each participating device. If the server reports UPDATE_REQUIRED, stop device interaction and direct that participant to the firmware updater. A channel-level response does not replace checking the actual device.

Use the agent reference for the complete endpoint index and the OpenAPI specification for request and response schemas.

Open an endpoint panel to try a request. Select Authorize inside that panel and use the credential described for its operation, then Try it out and Execute. Settings selects the API server and lets you hide inline examples in favor of the full Swagger UI.

Contents

Keep the identifiers and credentials distinct

Follow Developer access to create your account and obtain an Application ID (application_id) or Authentication Key (authentication_key) for the API. Keep Authentication Keys server-side. Use the credential and header required by each operation below.

The channel returns several values with different jobs. Keeping those jobs separate makes the rest of the API easier to follow.

Value Purpose
API credential for channel creation Creates a channel. Send it in X-Api-Key; the apikey query alternative is also supported.
Channel ID (channel_id) Identifies the channel in Channel API paths and its SSE URL.
Channel reference (channel_ref) Routes supported Handy REST commands to the group, with the chref: prefix.
Channel editor key (channel_key) Gives editor access to channel details, subscribers, and closure. Send it in X-Api-Key or apikey.
Subscriber key (subscriber_key) Lets someone add a subscriber. Send it in X-Api-Key or apikey.
Device connection key Identifies the device when joining. Use X-Connection-Key for device subscription listing and the explicit leave-all operation.
Subscriber ID (subscriber_id) Identifies one membership within a channel.
User authentication credential Lists the user's channels through X-Auth-Key; separate from the creation, editor, and join credentials.

Creation, editing, and joining use different credentials even though they share the X-Api-Key header name. Choose the credential required by the particular operation. Handy REST requests also require their own Handy REST authentication.

This contract does not define Channel client-token issuance. Use the operation-specific credentials above.

Share channel_key only with editors. Share subscriber_key with people who may join. Treat channel_ref as a control capability: someone who knows it can address the channel through supported Handy REST endpoints with the required Handy REST credentials. Channel lifecycle SSE needs only channel_id, so distribute that identifier with its event visibility in mind.

Create a channel

Give the channel a name and description that participants can recognize. The request body is required; the name and description are optional fields.

Replace the placeholders in each example with your own values. These are illustrative requests.

curl --silent --show-error --fail-with-body \
  --request POST \
  --header 'X-Api-Key: REPLACE_WITH_CHANNEL_API_CREDENTIAL' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Shared session","description":"A small group session","settings":{"offset":0,"device_events":false}}' \
  'https://www.handyfeeling.com/api/channel/v1/channels'

Open channel creation in Swagger UI.

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

A successful creation returns HTTP 200 and a Channel object. Save its channel_id, channel_ref, channel_key, and subscriber_key; later requests use the returned values. Entity responses are direct objects; collection responses have the shapes described in List channels and subscriptions.

The channel's settings.offset defaults to 0 milliseconds. Its settings.device_events defaults to false and controls whether the separate Handy REST SSE connection can receive device events for channel members.

Read the channel later with GET /channels/{channelId}, using its editor key.

Open channel details in Swagger UI.

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

Handy REST GET /info does not support Channel v1 references: it returns HTTP 200 with error.name: NOT_SUPPORTED (141008). Use individual device keys for firmware and hardware information.

Add a device

A device can belong to several channels. For each new membership, connection_key is required in the JSON body; settings is optional. Authenticate with the channel's subscriber_key.

curl --silent --show-error --fail-with-body \
  --request POST \
  --header 'X-Api-Key: REPLACE_WITH_SUBSCRIBER_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"connection_key":"REPLACE_WITH_DEVICE_CONNECTION_KEY","settings":{"type":"session","event_source":false}}' \
  'https://www.handyfeeling.com/api/channel/v1/channels/REPLACE_WITH_CHANNEL_ID/subscribers'

Open subscriber creation in Swagger UI.

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

This example omits the subscriber offset so it follows the channel's default delay, including later changes. The returned settings represent this choice as offset: -1. Set settings.offset to 0 explicitly when the subscriber should receive commands without that delay.

The response is HTTP 200 with a Subscriber object. Keep its subscriber_id and channel_id so an editor can manage that membership later. An active subscriber is receiving channel data. An inactive subscriber is not receiving data, for example while offline. A closed subscription must be created again to participate.

For a participant signup flow, give the participant the channel_id and subscriber_key, and let their client submit their own device key. This avoids requiring the channel creator to collect every participant's connection key. The editor credential is unnecessary for joining.

Send commands to the group

The Channel API manages the group. Movement commands go to supported Handy REST endpoints using:

X-Connection-Key: chref:REPLACE_WITH_CHANNEL_REF

Use channel_ref here, with the prefix exactly once. Continue using the returned channel_id in Channel API paths.

For example, this reads the group's HAMP state through Handy REST:

curl --silent --show-error --fail-with-body \
  --header 'X-Api-Key: REPLACE_WITH_HANDY_REST_APPLICATION_ID' \
  --header 'X-Connection-Key: chref:REPLACE_WITH_CHANNEL_REF' \
  'https://www.handyfeeling.com/api/handy-rest/v3/hamp/state'

Channel-reference support is defined per Handy REST method and path. Supported operations include mode reads/selection, HAMP controls, HVP controls, and global slider-stroke reads/updates. Check the compatibility summary and the Handy REST endpoint index before using chref:. A single subscriber or alias routing does not make every endpoint channel-compatible.

For example, this request goes to Handy REST v3:

GET /api/handy-rest/v3/info
X-Connection-Key: chref:REPLACE_WITH_CHANNEL_REF

It returns HTTP 200 with an operation-compatibility error:

{"error":{"code":141008,"name":"NOT_SUPPORTED","message":"Not supported","connected":true,"data":""}}

Use an individual device key for /info, and inspect the response body even when HTTP status is 200. This response does not describe the compatibility of other Handy REST endpoints.

Channel state uses the same units as Handy REST commands:

Value Unit
Global and HAMP stroke min/max Relative numbers from 0 through 1, inclusive.
HAMP velocity Number from 0 through 1 within the configured speed range.
HVP amplitude and slider position Relative numbers from 0 through 1, inclusive.
HVP frequency Hz, from 0 through 10000.

For example, 0.5 represents 50% of a relative range. HAMP stroke limits apply within the global slider range, just as they do for an individual device.

The response retains the Handy REST endpoint's usual format, but represents one channel-level response even if the group has many subscribers. Normal multicast forwarding returns once the channel accepts the data for forwarding. It does not wait for each subscriber's acknowledgement. A successful group response therefore does not confirm that every device received or executed the command. Read an individual device when you need its own state.

With ordinary multicast routing, GET /connected addressed through chref: tells you whether the channel is open. It is not a count or connectivity check for all subscribers.

Read GET /info with each participant's actual device key when checking firmware or hardware. A Channel v1 reference cannot provide that information.

Single-device alias responses

V1 also has a single-device alias mode. When this mode is enabled and the channel has exactly one subscriber, its chref: reference acts as a connection-key alias for that device. Supported Handy REST requests return the device's actual response, rather than the ordinary channel-level acknowledgement.

The response format still belongs to the selected Handy REST endpoint. The difference is its source: normal multicast acknowledges forwarding, while alias mode returns a response from the device. Check the endpoint's channel-reference support in either case.

GET /info remains unsupported through a Channel v1 reference, including with one subscriber. Alias behavior does not establish support for every Handy REST endpoint.

Choose how long membership lasts

Set settings.type when adding a subscriber:

Type Membership ends when
session — default The device disconnects, or the subscriber or channel closes.
connection_key The device connection key changes, or the subscriber or channel closes.
device The subscriber or channel closes.

Use session for a temporary shared session. Choose a longer-lived type when membership should survive a disconnect, and provide a way for the participant to leave. Persistence describes membership lifetime; it does not mean an offline device is receiving commands.

Pair devices through their controls

Set a subscriber's event_source to true during creation to let physical device controls affect the channel. Changes to stroke, speed, or vibration initiated by that device's buttons can then be forwarded to the other subscribers.

A channel can have several event sources. If all participating devices are event sources, each can influence the group through its controls. This is the channel's device-pairing use case.

event_source and channel device_events do different jobs. The former lets a subscriber contribute control-state changes. The latter enables monitoring device events through Handy REST SSE. Neither flag is needed simply to receive Channel API lifecycle events.

Adjust delivery delay

Supply nonnegative whole numbers in milliseconds when setting a delay. No upper limit is currently enforced. For example, 1000 delays forwarding by one second. A new subscriber follows the channel's current offset when its own offset is omitted. If the channel default is 1000, omitting the subscriber offset gives a one-second delay; explicitly sending offset: 0 gives no delivery delay.

A subscriber's explicit offset is its complete delivery delay. With a channel default of 1000 and a subscriber offset of 500, that subscriber's delay is 500 milliseconds.

Returned subscriber settings use -1 to indicate dynamic inheritance. If the channel default changes, these subscribers follow the new delay. The sentinel is a response value; sending offset: -1 in a create or update request is not supported by v1.

This is useful when device commands travel faster than a live video stream. Start with an estimate of the video delay, then let each participant adjust their subscriber offset for their own viewing setup. An offset is a delivery delay; precise external synchronization still depends on the selected movement protocol and its timing requirements.

Update the channel's settings with an editor key:

curl --silent --show-error --fail-with-body \
  --request PUT \
  --header 'X-Api-Key: REPLACE_WITH_CHANNEL_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"settings":{"offset":1000}}' \
  'https://www.handyfeeling.com/api/channel/v1/channels/REPLACE_WITH_CHANNEL_ID'

Changing the channel default also affects existing subscribers whose returned offset is -1. If the default changes from 1000 to 2000, those subscribers now use 2000 milliseconds. A subscriber with an explicit 500 continues using 500.

Open channel updates in Swagger UI.

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

Manage subscribers

Use channel_key to read, update, or close an individual membership.

To update a membership, send a settings object using SubscriberSettings: offset, event_source, type, and hw_model_no. The response is the updated Subscriber object, including its settings. The device_events flag belongs to channel settings and is configured through the channel endpoint.

For example, an editor can change a participant's delivery delay:

curl --silent --show-error --fail-with-body \
  --request PUT \
  --header 'X-Api-Key: REPLACE_WITH_CHANNEL_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"settings":{"offset":1500}}' \
  'https://www.handyfeeling.com/api/channel/v1/channels/REPLACE_WITH_CHANNEL_ID/subscribers/REPLACE_WITH_SUBSCRIBER_ID'

Open subscriber updates in Swagger UI.

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

Use GET on that same path to read a membership. GET /channels/{channelId}/subscribers, authenticated with channel_key, lists channel subscribers. It defaults to non-closed subscribers; status=active,inactive explicitly selects those two states.

Open membership details in Swagger UI.

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

Listen for channel events

Channel lifecycle events use the Channel API's SSE endpoint:

https://www.handyfeeling.com/api/channel/v1/channels/REPLACE_WITH_CHANNEL_ID/sse

This endpoint does not require a token or custom authentication header. Native browser EventSource can open it directly. An optional events query parameter is a comma-separated filter; omitting it subscribes to all events.

Event Meaning
channel_state Current channel state, on connection and state changes.
channel_closed The channel and its remaining subscribers have closed.
subscriber_added A member joined.
subscriber_closed A membership ended.
subscriber_inactive A member became inactive.
subscriber_activated A member became active.

For a membership that survives disconnection, subscriber_inactive reports the device going offline and subscriber_activated reports its return. These payloads identify the membership and can include its settings snapshot.

Each SSE frame has an id, an event name, and a JSON payload. The payload contains the event data directly:

id: EXAMPLE_EVENT_ID
event: subscriber_added
data: {"channel_id":"EXAMPLE_CHANNEL_ID","subscriber_id":"EXAMPLE_SUBSCRIBER_ID","settings":{"offset":-1,"type":"session","event_source":false}}

Fetch the current subscriber list separately; the SSE connection does not supply initial subscriber snapshots or settings-update notifications. Use the update response or read a membership when you need its current settings, and reconcile the list after reconnecting.

Register handlers for the named events:

const events = new EventSource(
  'https://www.handyfeeling.com/api/channel/v1/channels/REPLACE_WITH_CHANNEL_ID/sse'
);

function handle(event) {
  const data = JSON.parse(event.data);
  console.log(event.type, event.lastEventId, data);
  if (event.type === 'channel_closed') events.close();
}

for (const type of [
  'channel_state', 'channel_closed', 'subscriber_added',
  'subscriber_closed', 'subscriber_inactive', 'subscriber_activated'
]) {
  events.addEventListener(type, handle);
}

// Call events.close() when this view or session is finished.

For device-level events, use the separate Handy REST SSE endpoint, with its Handy REST credential, channel reference, and channel device_events=true. A Channel API lifecycle subscription does not replace that device-event connection.

sequenceDiagram
    participant C as Channel creator
    participant A as Channel API
    participant P as Participant
    participant R as Handy REST v3
    participant D as Active devices
    C->>A: Create channel with API credential
    A-->>C: Channel ID, reference, editor key, join key
    C-->>P: Share channel ID and join key
    P->>A: Join with own device connection key
    A-->>P: Subscriber ID and settings
    C->>R: Supported command with chref and REST credential
    R->>D: Forward to active subscribers
    R-->>C: One channel-level response
    A-->>C: Channel lifecycle events over Channel SSE

List channels and subscriptions

GET /channels lists a user's channels with the user-authentication credential in X-Auth-Key. The default status filter selects active channels. Its response has a top-level data array and pagination fields when applicable.

Open user-channel listing in Swagger UI.

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

GET /channels/{channelId}/subscribers uses the channel editor key and wraps its list in result:

{"result":{"cursor":"NEXT_CURSOR","data":[]}}

Read subscriber data from result.data and pagination fields from the same result object. Pagination metadata may include count, offset, and cursor.

Open the subscriber list in Swagger UI.

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

For those lists, limit is 1–1000, default 100; offset starts at 0. Supply the returned cursor for another page when available. A supplied cursor takes precedence over offset. Pagination offset is an element index; it is unrelated to the millisecond delivery delay.

GET /subscriptions uses the device connection key in X-Connection-Key and returns a direct array of non-closed memberships. The device must be online for this operation to return subscriptions. An empty result while offline is not proof that it has no memberships.

Open device subscriptions in Swagger UI.

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

End the session

End movement with the appropriate Handy REST stop command while the channel is still open. Then close the routing resources you no longer need.

  • PUT /channels/{channelId}/subscribers/{subscriberId}/close closes one membership. Use the editor key.
  • PUT /channels/{channelId}/close closes the channel and all remaining non-closed memberships. Use the editor key. The closed channel accepts neither commands nor new subscribers.
  • GET /subscriptions/close closes all non-closed memberships for the specified online device. Although its HTTP method is GET, this operation changes state; use it only for an explicit leave-all action.

For example, close a channel after finishing its controls:

curl --silent --show-error --fail-with-body \
  --request PUT \
  --header 'X-Api-Key: REPLACE_WITH_CHANNEL_KEY' \
  'https://www.handyfeeling.com/api/channel/v1/channels/REPLACE_WITH_CHANNEL_ID/close'

Open channel closure in Swagger UI.

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

To close only one membership, use its channel and subscriber IDs with the editor key:

Open membership closure in Swagger UI.

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

Use the leave-all operation only when the participant explicitly chooses to leave every non-closed membership for that device:

Open device leave-all in Swagger UI.

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

Closing a channel or an individual subscriber returns HTTP 200 with no response body. Do not try to parse JSON from these responses. Use a separate GET if you need the resulting resource state.

Channels are also closed automatically when no subscriber has been active for the preceding six hours. Plan explicit closure for your application flow rather than using stale-channel cleanup as its session timer.

For complete contracts, see the agent reference, OpenAPI specification, and Swagger UI.