Skip to content
Handyverse documentation

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

Open full Swagger UI
API documentation · The Handy Stream API v0View Markdown

Documentation 2026.11.15.1 · Tag docs-2026.11.15.1 · Version and checksums

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 for the walkthrough and OpenAPI spec 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. Follow this guide for authentication, workflows, and constraints that generated code may not enforce.

Use the API overview for agents 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, 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 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. 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 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.
{"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 for CSV/funscript encoding and scripting for authoring. StreamData is a bare array of 1–100 input points:

[{"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. 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. 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.