The Handy Hosting API v2
Hosting API v2 is stable. It gives a script a temporary URL that a playback service can fetch. Use it when your application has a local script file but no publicly reachable script host.
Its production base URL is:
https://www.handyfeeling.com/api/hosting/v2
Both Hosting operations require no API credential. You do not need an Application ID, Authentication Key, or client token to upload or download an ordinary script. Device playback uses the separate Handy REST API and its credentials.
Use the agent reference for exact fields and response handling, or the OpenAPI specification for the schemas.
The shared script-format reference covers funscript and Handy CSV encoding. Use the scripting guide when creating or reviewing a script.
If you need a test file, download a funscript from the demo video/script pairs, then use the upload workflow below.
You can run the requests with curl or use the inline Swagger UI panels in the web guide. Each operation also has a link to its full Swagger UI reference. Open Settings in the page header to choose the API server; that choice updates applicable Bash URLs and both inline operations. Use Copy to copy a complete Bash example. Inline examples are enabled by default. Turn them off in Settings if you prefer the full Swagger UI; this preference is saved for future visits. Open an operation by selecting its header, then select Try it out, enter the request values, and select Execute to send a request. No authorization is needed for either Hosting operation.
Upload a script
The API accepts Handy CSV and standard funscript JSON, including files with a .json extension. Send one file as multipart form field file.
For example, create a short CSV script and upload it:
Open POST /upload in Swagger UI
cat > motion.csv <<'CSV'
0,45
1000,55
2000,45
CSV
curl --silent --show-error --fail-with-body \
--form '[email protected];type=text/csv' \
'https://www.handyfeeling.com/api/hosting/v2/upload'
Use the curl example or linked Swagger UI operation if interactive controls are unavailable.
Replace motion.csv with your own script file when ready. The example uses standard funscript units: timestamps in milliseconds and positions from 0 through 100.
Let curl set the multipart Content-Type and its boundary. The field must be named file; the request body is not JSON containing a local path.
In Swagger UI, choose your script file for the file field before selecting Execute.
The file limit and the ingress request-body limit are both 10 MiB (10,485,760 bytes). The complete multipart request includes boundary and part headers, so leave room for that overhead when choosing a file. An oversized upload returns HTTP 413. No request rate limits are enforced.
A successful upload returns HTTP 200 with a JSON object containing url directly:
{"url":"https://www.handyfeeling.com/api/hosting/v2/download/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}
This URL is illustrative. Copy the actual URL from your response. An ordinary download URL contains a 64-character SHA-256 hex hash of the normalized script content. Equivalent funscript and CSV scripts produce the same hash. Use the returned URL unchanged.
Provider-issued script-token files use a funscript-compatible format and can be uploaded unchanged through the same file field. This lets a supported player keep the familiar video-and-script selection workflow while the server resolves script access and expiry. If the associated script token has expired, the request is still processed successfully and HTTP 200 contains error describing the outcome. Check the JSON body and continue to playback only when it provides a usable url.
For a valid script-token file, url is the token URL, rather than an ordinary /download/{scriptId} URL containing a SHA-256 hash. Pass it unchanged to the supported playback flow; do not extract a Hosting scriptId from it or assume ordinary hosted-script retention applies to token access.
Each upload response contains exactly one of url or error.
See Script tokens for provider access policies, distribution options, and playback use cases.
Download the hosted script
To inspect or save the ordinary hosted script, replace the placeholder with your returned URL:
Open GET /download/{scriptId} in Swagger UI
curl --silent --show-error --fail-with-body \
--output downloaded-script.csv \
'REPLACE_WITH_RETURNED_SCRIPT_URL'
Use the curl example or linked Swagger UI operation if interactive controls are unavailable.
The ordinary GET /download/{scriptId} endpoint always serves CSV, including scripts uploaded as funscript JSON. Treat the returned URL as the location to fetch, rather than rebuilding it from the upload endpoint.
In Swagger UI, enter the final 64-character identifier from an ordinary script's returned URL as scriptId. A token URL follows the script-token playback flow, rather than this hash-based download operation.
Ordinary downloads require no credential: someone with the URL can fetch the script. A script remains available for at least one hour after its last use. Every successful download and every upload of equivalent content refreshes that retention window. One hour is a minimum, rather than a precise deletion time.
Keep your original file. If the hosted script is no longer stored, downloading it returns HTTP 404 with an empty body; upload your source again when you need to host it.
Use the URL for playback
Pass the returned URL to Handy REST v3's HSSP (Handy Synchronized Script Protocol) setup operation, PUT /hssp/setup. That request uses a Handy REST Application ID or client token and the device connection key. Follow the HSSP walkthrough for compatibility checks, setup, clock synchronization, and playback.
For HSSP v3, the API server fetches the script. Temporary Hosting makes a local file accessible to that server without requiring your application to run its own public file server.
If the downloaded file is a script token, the server locates its associated script and checks token validity and device authorization. Only after those checks pass does it send the actual script's movement data to the device. See Script tokens for the file-to-URL and resolution sequence.
For a stored-script or live-data workflow, use the separate Stream API v0. It can import a reachable script URL and return a reusable stream_ref, which Handy REST's STREAM protocol uses for device playback. Stream API credentials and resource keys apply to those content operations.
Handle errors
| Response | Meaning and handling |
|---|---|
HTTP 200 with url |
Use the returned URL for playback. |
HTTP 200 with error |
Inspect the script-token outcome. For TOKEN_EXPIRED, stop the workflow and do not retry automatically. |
HTTP 400, empty body |
The required file is missing or its format/content cannot be parsed. Correct the request before trying again. |
HTTP 413 |
The upload exceeds a size limit. Reduce the complete multipart request size. The body may come from ingress, so do not assume JSON. |
HTTP 404, empty body |
The requested hosted script is not stored. |
An error object has code and name, and may include message and data. The data field can contain any valid JSON value. Preserve these details when reporting a problem. Script-token outcomes concern server-side content access; API client tokens used by Handy REST and Stream have their own authentication workflows.