--- format_version: 1 api_id: "hosting-v2" api_version: "v2" docs_version: "2026.11.15.1" docs_tag: "docs-2026.11.15.1" docs_revision: "71c47087c981d114b039587bb255cdc13ade92344ebfd98084e93b201f76dafb" source_revision: "02d17945187e6c91c4438aa8daa3e1b58e2cdcc8" body_sha256: "aafff8ccfa8d9c53f2daf4579f3627e84801e78869f9d6ebf76d90bcdcae1f43" updates: "https://links.handyfeeling.com/docs-hosting-api-v2-version" --- # 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](https://links.handyfeeling.com/docs-hosting-api-v2) for the walkthrough and [OpenAPI spec](https://links.handyfeeling.com/spec-hosting-api-v2) 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](https://links.handyfeeling.com/spec-hosting-api-v2). Follow this guide for authentication, workflows, and constraints that generated code may not enforce. Use the [API overview for agents](https://links.handyfeeling.com/docs-agent-index) 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 'file=@motion.csv;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](https://links.handyfeeling.com/docs-guide-script-tokens#use-a-token-file-like-a-funscript). 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](https://links.handyfeeling.com/docs-guide-script-tokens#a-token-as-a-file-or-url). 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. ```json {"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](https://links.handyfeeling.com/docs-guide-script-formats) for CSV/funscript encoding and the [scripting guide](https://links.handyfeeling.com/docs-guide-scripting) for authoring and review. Ready-made [demo videos and matching funscripts](https://links.handyfeeling.com/docs-guide-demo-content) 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](https://links.handyfeeling.com/docs-handy-rest-api-v3-agents#hssp-predetermined-scripts), 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](https://links.handyfeeling.com/docs-stream-api-v0-agents#creation-and-data-formats) 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.