--- format_version: 1 api_id: "stream-v0" api_version: "v0" docs_version: "2026.11.15.1" docs_tag: "docs-2026.11.15.1" docs_revision: "8ffa630b7287f8d8ef6777bc1ea77919d5b5fa3a032180715c038ac3f85be846" source_revision: "02d17945187e6c91c4438aa8daa3e1b58e2cdcc8" body_sha256: "bbf35c2287b87fa88225ba14de7dee8cb53505817ed2d41d9613ab7ff9c7f986" updates: "https://links.handyfeeling.com/docs-stream-api-v0-version" --- # The Handy Stream API v0: agent reference API release `0.1.0-beta`, OpenAPI `3.0.3`. Base URL: `https://www.handyfeeling.com/api/stream/v0`. Use the [human guide](https://links.handyfeeling.com/docs-stream-api-v0) for the walkthrough and [OpenAPI spec](https://links.handyfeeling.com/spec-stream-api-v0) for full schemas. The Stream API manages stored scripts and append-only live data. Handy REST v3's STREAM protocol manages device playback. Keep API credentials, resource keys, content references, and device session identifiers distinct. 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-stream-api-v0). 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, 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 Stream API operations. ## Credentials and identifiers 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 Stream. 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. | Value | Purpose and transport | | --- | --- | | Application ID | Stream creation; header `X-Api-Key` or query `apikey`. Must be issued for the Stream API. | | Authentication Key | User-stream listing; `Authorization: Bearer ...`. Keep server-side. | | Stream ID (`stream_id`) | Integer resource identifier; path parameter `streamId`. | | Stream reference (`stream_ref`) | String content reference; public SSE path `streamRef` and Handy REST STREAM setup. | | Stream data key (`data_key`) | Appending data; `X-Api-Key` or `apikey`. | | Stream editor key (`editor_key`) | Resource reads, metadata updates, finalization, and editor events. `X-Api-Key` or `apikey` for resource operations; query `apikey` for editor SSE. | | External reference (`external_ref`) | Application-defined optional identifier. Filter user streams with query `eref`. | Header/query alternatives are OR choices. The shared header `X-Api-Key` carries different credential roles on different operations. Use the credential declared for the selected operation. Stream client-token issuance is planned; use an Application ID for current creation requests. Never substitute Handy REST credentials. Per-stream keys are fixed; rotation and revocation are unavailable. `stream_key` is internal and is not a client identifier or credential. Public SSE requires knowledge of `stream_ref`. Device playback additionally requires Handy REST authentication and device addressing. Stream API `stream_id` identifies content; HSP `stream_id` identifies a device session. ## Endpoint index Paths below are relative to the Stream API base URL. Required `streamId` is an integer; required `streamRef` is a string. | Method and path | operationId | Authentication | Body / response | | --- | --- | --- | --- | | GET `/streams` | `getUserStreams` | Authentication Key (bearer) | No body; `{data: Stream[], meta: Meta}`, HTTP 200. | | POST `/streams` | `createStream` | Application ID | Required `StreamOpts` body; direct `StreamResponse`, HTTP 201. | | GET `/streams/{streamId}` | `getStream` | Stream editor key | No body; direct `StreamResponse`, HTTP 200. | | PUT `/streams/{streamId}` | `updateStream` | Stream editor key | Required object with optional `name`/`description`; direct `Stream`, HTTP 200. | | PUT `/streams/{streamId}/close` | `closeStream` | Stream editor key | No body; direct `Stream`, HTTP 200. | | PUT `/streams/{streamId}/data` | `appendStreamData` | Stream data key | Required bare `StreamData` array; `StreamChunk[]`, HTTP 200. | | GET `/streams/public/{streamRef}/sse` | `getPublicEvents` | Stream reference only | SSE; optional public event filter. | | GET `/streams/{streamId}/sse` | `getEvents` | Stream editor key in query `apikey` | SSE; optional editor event filter. | All resource paths are plural `/streams`. Authentication is required according to the row, not merely because another operation accepts a particular credential. Client-token issuance, renewal, and binding are outside current supported workflows. ## Creation and data formats `StreamOpts` has optional `name`, `description`, `external_ref`, and `content`. Body presence is required even when its properties are optional. For ready-made synchronization media, use the [demo video/script pairs](https://links.handyfeeling.com/docs-guide-demo-content). Import the selected funscript URL as `content.url`; the video stays in the player. Pass the returned `stream_ref`, not either media URL, to Handy REST device setup. - Omit `content` to create an open stream with `type: "live"` for appending data. - Supply one nonempty `content.actions`, `content.csv`, or `content.url` to create `type: "script"`, already closed and unable to receive further points. - A supplied URL must be reachable by the server and serve supported Handy CSV or funscript content. - [Hosting API v2](https://links.handyfeeling.com/docs-hosting-api-v2-agents) can provide a temporary reachable URL for a local file. Its upload requires no API credential; Stream creation still requires its own credential. - Supply exactly one content property when `content` is present; combining input formats is invalid. Empty `{}`, `actions: []`, `csv: ""`, or `url: ""` returns HTTP `400` with an empty body. ```json {"name":"Stored motion","content":{"actions":[{"at":0,"pos":0},{"at":1000,"pos":100}]}} ``` `Action` requires integer `at` and `pos`; `Point` requires integer `t` and `x`. Timestamps (`at`/`t`) are nonnegative whole milliseconds from stream start. Positions (`pos`/`x`) are integers within `[0,100]`. See [script formats](https://links.handyfeeling.com/docs-guide-script-formats) for CSV/funscript encoding and [scripting](https://links.handyfeeling.com/docs-guide-scripting) for authoring. `StreamData` is a bare array of 1–100 input points: ```json [{"t":0,"x":0},{"t":1000,"x":100}] ``` The server processes points in input order without sorting. Discard invalid points; accept a timestamp only if strictly greater than the last accepted timestamp, including across requests. Mixed batches return HTTP `200` with chunks for accepted points. The same validation/discard policy applies to imported content. No valid points, empty append arrays, more than 100 input points, and appends to closed streams return HTTP `400` with an empty body. An unchanged retry of an accepted batch has no new valid points and returns that error. There are no point insertion, replacement, or deletion operations. Ingress requests and normalized stored points each have a 10 MiB (10,485,760 byte) limit. Script imports exceeding the normalized limit return HTTP `413` with an empty API body. The 100-point limit applies only to append, not content import. An append reaching capacity stores the points that fit, drops overflow, and returns normal HTTP `200` chunks; later appends to the full stream return HTTP `413` with an empty body. Ingress rejection happens before API processing and may use its own response body. ## Responses and listing Creation and resource reads return a `StreamResponse` directly, not under `result`. Creation supplies the identifiers and role keys used by the workflow. Updates, finalization, and user-list entries use `Stream`; its required fields are `stream_id`, `created_at`, and `updated_at`. Additional properties describe references, timestamps, metadata, keys, and status. The metadata update request declares only `name` and `description`. Append returns an array of `StreamChunk` objects. Each requires integer `stream_id`, `created_at`, `updated_at`, `index_start`, `index_end`, `timestamp_start`, `timestamp_end`, and `chunk_length`. Indexes are absolute across the stream, zero-based, and inclusive; `chunk_length = index_end - index_start + 1`. Timestamp bounds are the first and last point's times in milliseconds from stream start. Use returned statistics to determine which points were stored, including capacity-limited appends. These records describe server storage, not device-buffer notifications. `type` is `script` or `live`; closing a live stream leaves its type unchanged. `status` is `active`, `error`, or `deactivated`; `error` is unrecoverable. `closed_at` independently records finalization: a closed stream can be `active`. Visibility (`access`) is `public`, `premium`, `private`, or `unlisted`, currently defaulting to `private`. GET `/streams` uses `eref` to filter by `external_ref`, plus pagination `limit` (integer `1–1000`, default `100`), `offset` (integer at least `0`, default `0`), and `cursor`. A cursor overrides offset. Read list pagination from the nested `meta` object. Inspect HTTP status and endpoint-specific bodies. Confirmed validation HTTP `400` and API-generated HTTP `413` responses have empty bodies; other declared resource errors use integer `code` and string `message`. Do not require a Handy REST device-error envelope on Stream API responses. ## Finalization and device playback PUT `/streams/{streamId}/close` finalizes input. No more points can be appended; the stored stream remains usable as script content. Finalization is separate from a device playback stop. Streams remain stored; closure and deactivation do not delete them. Creator-driven removal is planned. Live streams may deactivate after one hour without consumers; a consumer automatically reactivates them. Appending is permitted while deactivated and open, but does not itself reactivate the stream. Six hours without new data automatically closes a live stream. Hand off `stream_ref` to Handy REST `PUT /stream/setup`, then use its STREAM playback/synchronization operations with Handy REST credentials and the device connection key. See the [REST agent workflow](https://links.handyfeeling.com/docs-handy-rest-api-v3-agents#stream-stored-scripts-and-live-data). Apply the actual device's compatibility checks and clock synchronization there. The Stream API data/editor keys are for the content service. ### Provider-managed playback A provider can import script content on its backend, retain data/editor keys, and send the client only `stream_ref` for Handy REST setup. To keep the reference on the backend too, check entitlement and perform `PUT /stream/setup` there; acknowledge setup before client or backend playback controls. This keeps the raw script and source URL out of the client download flow. It does not create script tokens or add token-specific expiry, revocation or device binding. See [the shared playback comparison](https://links.handyfeeling.com/docs-guide-script-tokens#offer-playback-without-a-script-download). Keep the Stream creation credential separate from Handy REST device credentials. ## Stream events SSE uses `text/event-stream`. Native browser `EventSource` can connect to the public URL with `streamRef`, or the editor URL with `streamId` and URL-encoded query `apikey`. An optional comma-separated `events` filter selects from that endpoint's event set. | Event | Public | Purpose | | --- | --- | --- | | `stream_state` | Yes | Current stream state on connection and state changes. | | `stream_data_added` | Yes | Data appended to the stream. | | `stream_closed` | Yes | Input finalized. | | `stream_activated` | No | Stream activated. | | `stream_deactivated` | No | Stream deactivated. | | `stream_updated` | No | Stream properties updated. | | `stream_consumer_started` | No | Consumer started. | | `stream_consumer_closed` | No | Consumer closed. | | `stream_end_reached` | No | Consumer reached the end of an open or closed stream. | Frames use SSE `id:`, `event:`, and JSON `data:` fields. Dispatch on the named event; parse `event.data` as the direct payload, without an `{id,type,data}` JSON envelope. Both endpoints send a fresh `stream_state` snapshot on connection/reconnection only when selected by the filter; omission of the filter selects all events. `Last-Event-ID` replay is unsupported and there are no heartbeat messages. `stream_closed` leaves SSE connections open. Public snapshots omit credentials/internal fields; editor snapshots also omit data/editor keys. `stream_data_added` carries chunk index bounds, timestamp bounds, and point count, not points. `stream_deleted` is planned with stream removal. Stream events do not establish physical device state. Reconcile state on reconnect instead of expecting missed-event replay. Close local event connections when finished. Swagger UI documents SSE but does not test the persistent stream.