--- format_version: 1 api_id: "channel-v1" api_version: "v1" docs_version: "2026.11.15.1" docs_tag: "docs-2026.11.15.1" docs_revision: "51224b485d5c817eb67fc0b12e9bfe6619ad39b25a76479b81ba1b714b0770ca" source_revision: "02d17945187e6c91c4438aa8daa3e1b58e2cdcc8" body_sha256: "788e95c6a4f480150540384b5f8c6418c904cbeb0950e52520fcc22cb32d9f6a" updates: "https://links.handyfeeling.com/docs-channel-api-v1-version" --- # 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](https://links.handyfeeling.com/docs-channel-api-v1) explains the same workflow; the [OpenAPI specification](https://links.handyfeeling.com/spec-channel-api-v1) 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](https://links.handyfeeling.com/spec-channel-api-v1). Follow this guide for authentication, workflows, and constraints that generated code may not enforce. Use the [API overview for agents](https://links.handyfeeling.com/docs-agent-index) 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](https://links.handyfeeling.com/docs-handy-rest-api-v3-agents#compatibility): `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](https://links.handyfeeling.com/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](https://links.handyfeeling.com/docs-guide-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.