# 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: ```text 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](https://links.handyfeeling.com/docs-hosting-api-v2-agents) for exact fields and response handling, or the [OpenAPI specification](https://links.handyfeeling.com/spec-hosting-api-v2) for the schemas. The shared [script-format reference](https://links.handyfeeling.com/docs-guide-script-formats) covers funscript and Handy CSV encoding. Use the [scripting guide](https://links.handyfeeling.com/docs-guide-scripting) when creating or reviewing a script. If you need a test file, download a funscript from the [demo video/script pairs](https://links.handyfeeling.com/docs-guide-demo-content), 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](https://links.handyfeeling.com/swagger-hosting-api-v2-upload) ```bash cat > motion.csv <<'CSV' 0,45 1000,55 2000,45 CSV curl --silent --show-error --fail-with-body \ --form 'file=@motion.csv;type=text/csv' \ 'https://www.handyfeeling.com/api/hosting/v2/upload' ``` 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: ```json {"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](https://links.handyfeeling.com/docs-guide-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](https://links.handyfeeling.com/swagger-hosting-api-v2-download) ```bash curl --silent --show-error --fail-with-body \ --output downloaded-script.csv \ 'REPLACE_WITH_RETURNED_SCRIPT_URL' ``` 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](https://links.handyfeeling.com/docs-guide-script-tokens#a-token-as-a-file-or-url), 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](https://links.handyfeeling.com/docs-handy-rest-api-v3-hssp) 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](https://links.handyfeeling.com/docs-guide-script-tokens#a-token-as-a-file-or-url) for the file-to-URL and resolution sequence. For a stored-script or live-data workflow, use the separate [Stream API v0](https://links.handyfeeling.com/docs-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.