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 Hosting API v2View Markdown

Documentation 2026.11.15.1 · Tag docs-2026.11.15.1 · Version and checksums

The Handy Hosting API v2: agent reference

Stable API, release 2.0.0, OpenAPI 3.0.3. Production base URL: https://www.handyfeeling.com/api/hosting/v2. See the human guide for the walkthrough and OpenAPI spec for full schemas.

The Hosting API accepts script files and returns temporary fetch URLs. Handy REST controls device playback; Stream manages stored scripts and append-only live data. Keep these API roles 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 Hosting API operations.

Operations and authentication

Account signup is unnecessary for these Hosting upload and download operations. An integration that also uses Handy REST, Stream or Channel must obtain that API's credentials separately.

Method and path operationId Authentication Request / response
POST /upload upload None; security: [] Required multipart/form-data, required binary field file; HTTP 200 JSON UploadResponse.
GET /download/{scriptId} download None; security: [] Required string scriptId; HTTP 200 text/csv body.

No Application ID, Authentication Key, client token, or device connection key is required by these operations. This specification declares no API client-token issuance operation. Script-token information and expiry are managed server-side; clients upload standard script data through the same workflow.

Upload contract

Send Handy CSV or standard funscript JSON in multipart field file. A .json script uses the funscript structure. For curl, use --form '[email protected];type=text/csv' and let curl construct the multipart boundary. Do not send JSON wrapping the file path, use a different field name, or forward device credentials.

Provider-issued script-token files use the funscript-compatible file workflow. Pass the issued file unchanged through the same file field so the service can resolve script access server-side. Treat its carrier data as opaque; do not reinterpret it as editable movement, manufacture token fields, or assume another action parser resolves token access. See token-file compatibility.

A valid script-token upload returns its token URL in url, rather than an ordinary hash-based Hosting download URL. Pass the returned URL unchanged to the supported playback setup. Do not parse it as /download/{scriptId}, apply the ordinary script's minimum retention period to token access, or derive a token URL from the file. See file and URL resolution.

Both the file-size limit and ingress request-body limit are 10485760 bytes (10 MiB). The complete multipart request must fit, including boundary and part headers; a file at the full limit leaves no room for that overhead. Oversized uploads return HTTP 413. No request rate limits are enforced.

The upload response is direct JSON, without a Handy REST result wrapper:

  • Success: UploadResult, requiring string url.
  • Script-token validation outcome: UploadError, requiring object error, returned with HTTP 200 when the upload request was processed but the represented script token is unusable, for example expired.
  • UploadResponse selects between those shapes. Exactly one of url or error is present. Inspect HTTP status and the JSON body before proceeding.
{"url":"https://www.handyfeeling.com/api/hosting/v2/download/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}

The URL is illustrative. Use the actual returned URL unchanged. For an ordinary download, scriptId matches ^[a-fA-F0-9]{64}$ and hashes normalized script content. Equivalent funscript and CSV content produces the same identifier. The service performs normalization.

Download and lifecycle

GET /download/{scriptId} always returns CSV text, including scripts uploaded as funscript JSON. Do not parse the successful body as a JSON device response. A valid identifier with no stored script returns HTTP 404 with an empty body.

That endpoint describes ordinary hash-addressed scripts. When the playback server downloads a file and recognizes a script token, it resolves the associated script and validates the token and intended device before delivering the actual movement data. A returned token URL is not an additional Hosting endpoint declared by this specification.

The ordinary download endpoint requires no credential. Treat its URL as shareable access to the hosted content. Storage is retained for at least 3600 seconds (1 hour) after last use. Each successful download and each upload of equivalent normalized content refreshes that minimum retention window. This is not a guaranteed deletion time. Retain the original source for re-hosting when necessary. This API exposes no list, update, explicit delete, or client-token renewal operation.

Scripts use standard funscript units: timestamps in milliseconds and positions from 0 through 100.

Use the shared script-format reference for CSV/funscript encoding and the scripting guide for authoring and review.

Ready-made demo videos and matching funscripts are available for file-upload and playback integration tests. Download a funscript before uploading it; the video is not a Hosting script input.

Errors

APIErrorObject requires numeric code and string name; optional fields are string message and data containing any valid JSON value, including arrays, numbers, booleans, strings, objects, and null. Script-token validation results are nested under error. HTTP 200 indicates that the upload request was processed; an expired script token is reported in the body using that status. Inspect the body for a usable URL before proceeding.

HTTP outcome Contract
POST /upload, 400 Missing file or unparseable/unsupported format/content; empty response body.
POST /upload, 413 File or complete multipart request exceeds its limit. The body is implementation-dependent and may be ingress-generated HTML; do not require JSON.
GET /download/{scriptId}, 404 No stored script; empty response body.

Check HTTP status before attempting to parse JSON. Only a processed upload's HTTP 200 body follows UploadResponse.

Script-token error examples include:

Code Name Meaning
2000 TOKEN_ERROR Unspecified token error.
2001 TOKEN_URL_EXPIRED Token URL expired.
2002 TOKEN_EXPIRED Script token expired.
2003 TOKEN_INVALID Invalid script token.
2004 TOKEN_RESTRICTED Token cannot be used in the current context.
2005 TOKEN_URL_INVALID Invalid token URL.

These are Hosting error meanings; do not substitute Handy REST device-error meanings for matching numbers. Treat TOKEN_EXPIRED as terminal: stop the workflow without automatic retry or a client-token renewal attempt.

Playback handoff

Pass the returned script URL to Handy REST PUT /hssp/setup, with Handy REST authentication and device addressing. Continue with the HSSP agent workflow, including compatibility and clock synchronization. In HSSP v3, the API server fetches the URL.

For managed stored-script/live-data workflows, import a reachable URL through the Stream API using its own creation credentials, then pass its stream_ref to Handy REST STREAM setup. Hosting's returned url is not a stream_ref, Stream resource ID, device connection key, or API client token.