# The Handy Stream API v0 A stream stores movement points on the servers so they can be played on a device. You can create a complete script for later reuse, or keep a stream open and append movements as your application produces them. The Stream API manages that content. The separate [Handy REST API v3](https://links.handyfeeling.com/docs-handy-rest-api-v3-stream) sets up and controls device playback through its STREAM protocol. This keeps content management and device control independent: several devices can play the same accessible stream. Stream API v0 is in beta. Its production base URL is: ```text https://www.handyfeeling.com/api/stream/v0 ``` Use the [agent reference](https://links.handyfeeling.com/docs-stream-api-v0-agents) for exact operations and fields, and the [OpenAPI specification](https://links.handyfeeling.com/spec-stream-api-v0) for the complete schemas. Replace the placeholders in the examples with your own values. Open an endpoint panel to try a request. Select **Authorize** inside that panel and use the Application ID, data key, or editor key required by the 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. ## Credentials and references Follow [Developer access](https://links.handyfeeling.com/docs-guide-developer-access) to obtain an Application ID (`application_id`) or Authentication Key (`authentication_key`) for the Stream API. Credentials must be issued for the correct API. If the account cannot issue Stream credentials, ask your platform support contact about Stream API access. | Value | Purpose | | --- | --- | | Application ID | Creates streams through `X-Api-Key` or query `apikey`. | | Authentication Key | Lists your streams from your server; `Authorization: Bearer ...`. | | Stream ID (`stream_id`) | Numeric resource identifier used in editor and data endpoint paths. | | Stream reference (`stream_ref`) | Identifies content for public events and Handy REST STREAM setup. | | Stream data key (`data_key`) | Authorizes appending points; `X-Api-Key` or `apikey`. | | Stream editor key (`editor_key`) | Authorizes reads, metadata updates, finalization, and editor events. | | External reference (`external_ref`) | Your optional identifier, used to find streams later with query `eref`. | The Application ID and Authentication Key are distinct from the per-stream keys returned during creation. Keep Authentication Keys on your server. Give producers the stream's ID and data key; give editors its ID and editor key. These per-stream keys are fixed; rotation and revocation are not available. Device playback also requires the participant's Handy REST credential and device connection key. Stream client-token issuance is planned. Use an Application ID for current stream-creation requests; keep Handy REST authentication separate when controlling a device. ## Store an existing script Include one content option when creating the stream: | Content field | Input | | --- | --- | | `actions` | Funscript-style objects with timestamp `at` and position `pos`. | | `csv` | Inline Handy CSV script text. | | `url` | Publicly accessible URL serving Handy CSV or funscript data. | Provide only one content option. The server must be able to download a supplied URL; a private-network-only host will not work. If you need a temporary public URL for a local file, use [Hosting API v2](https://links.handyfeeling.com/docs-hosting-api-v2), then supply its returned URL as `content.url` with your Stream API creation credential. For a synchronization test without your own content, choose a [demo video and matching funscript](https://links.handyfeeling.com/docs-guide-demo-content). Use this creation body to import the recommended script by URL: ```json {"name":"Synchronization demo","content":{"url":"https://sweettecheu.s3.eu-central-1.amazonaws.com/synctest26/sync_video_60fps_web.funscript"}} ``` For example, this stores three movements as a reusable script: ```bash curl --silent --show-error --fail-with-body --request POST \ --header 'X-Api-Key: REPLACE_WITH_STREAM_APPLICATION_ID' \ --header 'Content-Type: application/json' \ --data '{"name":"Video motion","description":"A reusable movement script","external_ref":"video-123","content":{"actions":[{"at":0,"pos":0},{"at":1000,"pos":100},{"at":2000,"pos":0}]}}' \ 'https://www.handyfeeling.com/api/stream/v0/streams' ``` [Stream creation reference](https://links.handyfeeling.com/swagger-stream-api-v0-create). Creation returns HTTP `201` with the stream object directly. Save `stream_id`, `stream_ref`, `data_key`, and `editor_key` from that object. These fields are not inside a Handy REST `result` wrapper. A stream created with content has `type: "script"` and is already closed: its data is finalized and no further points can be appended. It remains content for playback. Names and descriptions help people recognize a stream; `external_ref` can connect it to a video, game effect, or identifier in your application. Scripts use standard funscript values: nonnegative integer millisecond timestamps and integer positions from `0` through `100`. See [script formats](https://links.handyfeeling.com/docs-guide-script-formats) for file examples and [scripting](https://links.handyfeeling.com/docs-guide-scripting) for authoring. The server processes points in their supplied order, without sorting. Invalid points, including timestamps not strictly greater than the last accepted timestamp, are discarded. An import with no valid points returns HTTP `400` with an empty body. Supply exactly one nonempty content option. An empty content object or an empty URL, CSV string, or actions array returns HTTP `400` with an empty body. Omit `content` entirely when creating a live stream. The complete ingress request and normalized stream data each have a **10 MiB (10,485,760 byte)** limit. A script import exceeding the normalized limit is rejected with HTTP `413` and an empty API response body. Ingress can reject an oversized request before the API processes it. ## Create a stream for live data Omit `content` to create an open stream with `type: "live"`: ```bash curl --silent --show-error --fail-with-body --request POST \ --header 'X-Api-Key: REPLACE_WITH_STREAM_APPLICATION_ID' \ --header 'Content-Type: application/json' \ --data '{"name":"Live motion","external_ref":"live-123"}' \ 'https://www.handyfeeling.com/api/stream/v0/streams' ``` [Open live-stream creation in Swagger UI](https://links.handyfeeling.com/swagger-stream-api-v0-create). Save its returned identifiers and keys, then append points using the data key: ```bash curl --silent --show-error --fail-with-body --request PUT \ --header 'X-Api-Key: REPLACE_WITH_STREAM_DATA_KEY' \ --header 'Content-Type: application/json' \ --data '[{"t":0,"x":0},{"t":1000,"x":100}]' \ 'https://www.handyfeeling.com/api/stream/v0/streams/REPLACE_WITH_STREAM_ID/data' ``` [Append-data reference](https://links.handyfeeling.com/swagger-stream-api-v0-append). The body is an array of **1–100 points**, not an object containing `points`. Each point requires integer `t` and `x`, using the same timestamp and position rules as imported scripts. Use the movement timeline for timestamps, rather than the time the HTTP request was sent. The server processes points in request order and discards invalid ones. Each accepted timestamp must be strictly greater than the last accepted timestamp, including across requests. For example, timestamps `[100, 200, 150, 300]` retain `100`, `200`, and `300`. Mixed batches return HTTP `200` with records describing the accepted data. Each returned chunk has a numeric `stream_id`. Its `index_start` and `index_end` are zero-based, inclusive indexes across the whole stream; `chunk_length` is their point count. `timestamp_start` and `timestamp_end` are the first and last point times in milliseconds from stream start. A first chunk containing three points spans indexes `0–2`; the next begins at `3`. An empty array, more than 100 input points, no valid points, or an append to a closed stream returns HTTP `400` with an empty body. Retrying an already accepted batch also leaves no new valid points and returns that error. Appending does not insert, replace, or delete existing data. The stream's normalized data is limited to 10 MiB. An append that reaches capacity stores the points that fit, drops overflow, and returns the normal HTTP `200` chunk response. Check those chunk statistics to see what was stored. Once full, subsequent appends return HTTP `413` with an empty body. The 100-point limit applies to append requests, not script imports. ## Play the stream on a device Give the saved `stream_ref` to Handy REST's `PUT /stream/setup`. Use a Handy REST Application ID or client token and the device connection key for that request. The Stream API data/editor keys are used for content operations. The [Handy REST STREAM guide](https://links.handyfeeling.com/docs-handy-rest-api-v3-stream) covers setup, play, stop, and clock synchronization. For video synchronization, follow its timing workflow and supply a fresh server-time estimate during playback control. Server-side delivery replenishes the device buffer as needed. Stream API `stream_id` identifies stored content. Handy REST HSP's `stream_id` is a device-session identifier; the two fields belong to different contexts. ```mermaid sequenceDiagram participant A as Application participant S as Stream API participant R as Handy REST v3 participant D as Device A->>S: Create content with Stream API credential S-->>A: Stream reference and resource keys A->>R: Setup stream_ref with REST credential and device key R->>S: Consume stored or incoming movement data S-->>R: Movement points R->>D: Fill playback buffer A->>R: Play and synchronize device playback A->>S: Append live points using data_key S-->>R: Additional movement points R->>D: Refill playback buffer ``` ### Prepare content on your backend A content provider can import scripts through its backend and give the player only a `stream_ref`, so the player does not need a script download or source URL. Your backend can also complete Handy REST's `PUT /stream/setup` after checking the user's access, keeping the reference there too. Keep the stream's data/editor keys on the backend; device setup and playback use separate Handy REST credentials. See [playback without a script download](https://links.handyfeeling.com/docs-guide-script-tokens#offer-playback-without-a-script-download) for this workflow, backend HSSP setup and their distinction from script tokens. ## Manage and finalize a stream Use the stream editor key to read its details: ```bash curl --silent --show-error --fail-with-body \ --header 'X-Api-Key: REPLACE_WITH_STREAM_EDITOR_KEY' \ 'https://www.handyfeeling.com/api/stream/v0/streams/REPLACE_WITH_STREAM_ID' ``` [Stream details reference](https://links.handyfeeling.com/swagger-stream-api-v0-get). The metadata update accepts `name` and `description`: ```bash curl --silent --show-error --fail-with-body --request PUT \ --header 'X-Api-Key: REPLACE_WITH_STREAM_EDITOR_KEY' \ --header 'Content-Type: application/json' \ --data '{"name":"Final motion","description":"A recorded live session"}' \ 'https://www.handyfeeling.com/api/stream/v0/streams/REPLACE_WITH_STREAM_ID' ``` [Metadata update reference](https://links.handyfeeling.com/swagger-stream-api-v0-update). When the producer has finished adding data, close the stream: ```bash curl --silent --show-error --fail-with-body --request PUT \ --header 'X-Api-Key: REPLACE_WITH_STREAM_EDITOR_KEY' \ 'https://www.handyfeeling.com/api/stream/v0/streams/REPLACE_WITH_STREAM_ID/close' ``` [Stream finalization reference](https://links.handyfeeling.com/swagger-stream-api-v0-close). Closing finalizes the stored data, making the live stream reusable as completed content. Its `type` remains `live`; `closed_at` records closure independently of `status`. A closed stream can still be `active`. Stop device movement through Handy REST's playback controls when needed; finalizing the content is a separate operation. Streams are retained; closing or deactivating them does not delete their data. Creator-driven removal is planned. Live streams may deactivate after one hour without consumers and automatically reactivate when a consumer connects. You can append while deactivated if the stream is still open, but appending alone does not reactivate it. After six hours without new data, a live stream closes automatically. The `status` values are `active`, `deactivated`, and `error`; `error` is unrecoverable. Visibility (`access`) currently defaults to `private`; the visibility values are `public`, `premium`, `private`, and `unlisted`. Use the documented identifiers: the response's `stream_key` is for internal use. ## Find your streams List streams from your server using its Stream Authentication Key. To find a stream using your external identifier, send query `eref`: ```bash curl --silent --show-error --fail-with-body --get \ --header 'Authorization: Bearer REPLACE_WITH_STREAM_AUTHENTICATION_KEY' \ --data-urlencode 'eref=video-123' \ --data-urlencode 'limit=100' \ 'https://www.handyfeeling.com/api/stream/v0/streams' ``` [User-stream listing reference](https://links.handyfeeling.com/swagger-stream-api-v0-list). The response contains `data`, an array of streams, and `meta`, the pagination information. `limit` is `1–1000` and defaults to `100`; pagination `offset` starts at `0`. A supplied cursor overrides offset. Use `meta.cursor` for further pages when returned. ## Listen for stream events Public events need only the stream reference: ```javascript const streamRef = "REPLACE_WITH_STREAM_REFERENCE"; const url = "https://www.handyfeeling.com/api/stream/v0/streams/public/" + encodeURIComponent(streamRef) + "/sse"; const events = new EventSource(url); function handle(event) { console.log(event.type, JSON.parse(event.data)); } for (const type of ["stream_state", "stream_data_added", "stream_closed"]) { events.addEventListener(type, handle); } // When the view is finished: // events.close(); ``` [Public-events reference](https://links.handyfeeling.com/swagger-stream-api-v0-public-events). Events are named SSE frames with direct JSON payloads. For example: ```text id: EXAMPLE_EVENT_ID event: stream_data_added data: {"stream_id":123,"index_start":0,"index_end":1,"timestamp_start":0,"timestamp_end":1000,"chunk_length":2} ``` `stream_data_added` reports chunk indexes, timestamps, and point count; it does not deliver the movement points. Public and editor snapshots omit data/editor credentials; public snapshots also omit internal fields. Editors can receive additional events using the numeric stream ID and editor key in query `apikey`: ```bash curl --no-buffer --get \ --data-urlencode 'apikey=REPLACE_WITH_STREAM_EDITOR_KEY' \ 'https://www.handyfeeling.com/api/stream/v0/streams/REPLACE_WITH_STREAM_ID/sse' ``` [Editor-events reference](https://links.handyfeeling.com/swagger-stream-api-v0-editor-events). Editor events also cover activation, deactivation, updates, consumers starting/closing, and consumers reaching the end of either open or closed streams. Deletion and its `stream_deleted` event are planned. Both endpoints send a fresh `stream_state` snapshot on connection and reconnection, subject to the optional comma-separated `events` filter. Include `stream_state` in a supplied filter to receive that snapshot; omit the filter to receive all available events. `Last-Event-ID` replay is not supported, and the server sends no heartbeat messages. Finalization sends `stream_closed` without closing the SSE connection. Stream events concern stored data and its consumers. Use Handy REST's separate device events when you need device playback state. Reconcile state after reconnecting rather than expecting missed events to replay. Close event connections when finished. Swagger UI shows the SSE reference but does not exercise a persistent event stream. Check HTTP status and the endpoint-specific response body throughout the workflow. Token issuance uses its `result`/`error` shape; other operations use the direct stream, chunk-array, or paginated response described above. The [agent reference](https://links.handyfeeling.com/docs-stream-api-v0-agents) lists each contract and event type.