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 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:
https://www.handyfeeling.com/api/stream/v0
Use the agent reference for exact operations and fields, and the OpenAPI specification 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 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, 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. Use this creation body to import the recommended script by URL:
{"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:
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'
Use the curl example or linked Swagger UI operation if interactive controls are unavailable.
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 for file examples and 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":
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.
Use the curl example or linked Swagger UI operation if interactive controls are unavailable.
Save its returned identifiers and keys, then append points using the data key:
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'
Use the curl example or linked Swagger UI operation if interactive controls are unavailable.
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 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.
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 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:
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'
Use the curl example or linked Swagger UI operation if interactive controls are unavailable.
The metadata update accepts name and description:
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'
Use the curl example or linked Swagger UI operation if interactive controls are unavailable.
When the producer has finished adding data, close the stream:
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.
Use the curl example or linked Swagger UI operation if interactive controls are unavailable.
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:
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.
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:
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();
Events are named SSE frames with direct JSON payloads. For example:
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:
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 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 lists each contract and event type.