Vacuglide API V1

Selecting A Cluster

The Vacuglide API is hosted on multiple clusters around the world. When a device goes online it will connect to the lowest latency server. To control the device you must connect to the same cluster as the device. You can find the cluster your device is connected to by checking the cluster property in the /vacuglide/connected response.

https://us-east-1.autoblowapi.com
https://us-east-2.autoblowapi.com
https://us-west-1.autoblowapi.com
https://us-west-2.autoblowapi.com
https://ca-central-1.autoblowapi.com
https://ap-southeast-2.autoblowapi.com
https://eu-west-2.autoblowapi.com
https://eu-central-1.autoblowapi.com

Every request below takes the device token in the x-device-token header. Requests with a body use Content-Type: application/json; send requests without a body without a Content-Type header. Most commands respond with the device state; the ones that return something else say so. The examples use the eu-central-1 cluster and YOUR_DEVICE_TOKEN.

Online Mode

The Vacuglide only takes commands while it is in online mode. The user turns online mode on or off by holding the mode button for about 2.5 seconds; the device connects to its cluster when online mode starts and disconnects when it ends. While it is disconnected, /vacuglide/connected returns { "connected": false } and commands fail with 502. In online mode the speed and mode buttons no longer control the device; their presses are sent as device events instead.

Basic Requests

GET /vacuglide/connected

Check if a device is connected and get the cluster it is connected to. This request can be performed on any cluster but for reliability purposes we recommend using https://latency.autoblowapi.com which will connect you to the cluster with the lowest latency. All the other requests can only be performed on the cluster the device is connected to.

curl --request GET \
     --url https://latency.autoblowapi.com/vacuglide/connected \
     --header 'x-device-token: YOUR_DEVICE_TOKEN'

{ "connected": true, "cluster": "eu-central-1.autoblowapi.com", "deviceType": "vacuglide" }

GET /vacuglide/info

Get the firmware and hardware version and the device MAC. firmwareStatus is UP_TO_DATE, UPDATE_AVAILABLE or UPDATE_REQUIRED.

curl --request GET \
     --url https://eu-central-1.autoblowapi.com/vacuglide/info \
     --header 'x-device-token: YOUR_DEVICE_TOKEN'

{
  "firmwareStatus": "UP_TO_DATE",
  "firmwareVersion": 1.01,
  "firmwareBranch": "prod",
  "hardwareVersion": "vacuglide",
  "mac": "aabbccddeeff",
  "deviceType": "vacuglide"
}

GET /vacuglide/state

Get the current device state.

curl --request GET \
     --url https://eu-central-1.autoblowapi.com/vacuglide/state \
     --header 'x-device-token: YOUR_DEVICE_TOKEN'

Valve Commands

PUT /vacuglide/valve/stroke-plus, /vacuglide/valve/stroke-minus

Open or close the stroke plus or stroke minus valve. Selecting a local script or starting a sync script closes both valves.

name	required	type	description
valveState (body)	yes	bool	true opens the valve, false closes it

curl --request PUT \
     --url https://eu-central-1.autoblowapi.com/vacuglide/valve/stroke-plus \
     --header 'Content-Type: application/json' \
     --header 'x-device-token: YOUR_DEVICE_TOKEN' \
     --data '{"valveState": true}'

Target Speed Commands

PUT /vacuglide/target-speed

Run the motor at a constant speed. The device switches to TARGET_SPEED_PLAYING.

name	required	type	description
targetSpeed (body)	yes	number	Speed in percent (0 to 100)

curl --request PUT \
     --url https://eu-central-1.autoblowapi.com/vacuglide/target-speed \
     --header 'Content-Type: application/json' \
     --header 'x-device-token: YOUR_DEVICE_TOKEN' \
     --data '{"targetSpeed": 50}'

PUT /vacuglide/target-speed/stop

Stop the motor, whatever is playing. The device switches to TARGET_SPEED_PAUSED. No body.

curl --request PUT \
     --url https://eu-central-1.autoblowapi.com/vacuglide/target-speed/stop \
     --header 'x-device-token: YOUR_DEVICE_TOKEN'

Local Script Commands

The Vacuglide stores 30 local scripts, numbered 0 to 29.

PUT /vacuglide/local-script

Play a local script from the start. The device switches to LOCAL_SCRIPT_PLAYING.

name	required	type	description
localScriptIndex (body)	yes	number	Script to play (0 to 29)

curl --request PUT \
     --url https://eu-central-1.autoblowapi.com/vacuglide/local-script \
     --header 'Content-Type: application/json' \
     --header 'x-device-token: YOUR_DEVICE_TOKEN' \
     --data '{"localScriptIndex": 5}'

PUT /vacuglide/local-script/start, /vacuglide/local-script/stop

Resume or pause the selected local script. start only acts in LOCAL_SCRIPT_PAUSED and stop only in LOCAL_SCRIPT_PLAYING; in any other mode they return the state unchanged, so use /vacuglide/local-script to start a script from another mode. No body.

curl --request PUT \
     --url https://eu-central-1.autoblowapi.com/vacuglide/local-script/start \
     --header 'x-device-token: YOUR_DEVICE_TOKEN'

Sync Script Commands

Sync scripts play a funscript in sync with a video. Upload a script (or load one uploaded earlier by its token), then call start with the video position whenever the video starts playing or the user seeks. The Vacuglide plays speeds, not positions: the backend turns how fast the position changes between two actions into a motor speed. A script can have up to 100,000 actions and must end within 16,777,214 ms (about 4.6 hours).

A CSV script has one at,pos line per action, with at in ms and pos as in a funscript. End the file with a newline, otherwise its last action is dropped.

PUT /vacuglide/sync-script/load-token

Loads a previously uploaded script by token. The device downloads the script before responding, so allow a request timeout of at least 60 seconds. Loading never starts playback; the device ends in SYNC_SCRIPT_PAUSED.

name	required	type	description
scriptToken (body)	yes	string	Token returned by an upload

curl --request PUT \
     --url https://eu-central-1.autoblowapi.com/vacuglide/sync-script/load-token \
     --header 'Content-Type: application/json' \
     --header 'x-device-token: YOUR_DEVICE_TOKEN' \
     --data '{"scriptToken": "7a93bfc5-4043-4ade-aee5-bec8012b0e12"}'

PUT /vacuglide/sync-script/upload-funscript, /vacuglide/sync-script/upload-csv

Uploads a funscript or CSV file as multipart/form-data; curl sets that Content-Type header itself. The backend stores the script under a new token and loads it on the device like load-token, so allow a request timeout of at least 60 seconds. The token is returned in the syncScriptToken field of the device state and stays valid for 9 days.

name	required	type	description
file (multipart)	yes	file	The funscript or CSV file

curl --request PUT \
     --url https://eu-central-1.autoblowapi.com/vacuglide/sync-script/upload-funscript \
     --header 'x-device-token: YOUR_DEVICE_TOKEN' \
     --form 'file=@/path/to/script.funscript'

PUT /vacuglide/sync-script/upload-funscript-url, /vacuglide/sync-script/upload-csv-url

Same as the file uploads, but the backend downloads the file from a URL. The URL must serve the file directly; redirects are not followed.

name	required	type	description
url (body)	yes	string	URL of the funscript or CSV file

curl --request PUT \
     --url https://eu-central-1.autoblowapi.com/vacuglide/sync-script/upload-funscript-url \
     --header 'Content-Type: application/json' \
     --header 'x-device-token: YOUR_DEVICE_TOKEN' \
     --data '{"url": "https://vieci-uploads.s3.amazonaws.com/funscripts/test.funscript"}'

PUT /vacuglide/sync-script/start

Starts, resumes or seeks to a video position. Send it whenever the video starts playing or the user seeks. Fails with 400 when no script is loaded.

name	required	type	description
startTimeMs (body)	yes	number	Video position in ms

curl --request PUT \
     --url https://eu-central-1.autoblowapi.com/vacuglide/sync-script/start \
     --header 'Content-Type: application/json' \
     --header 'x-device-token: YOUR_DEVICE_TOKEN' \
     --data '{"startTimeMs": 0}'

PUT /vacuglide/sync-script/stop

Pauses playback. The script stays loaded, so a later start resumes or seeks without downloading again. No body.

curl --request PUT \
     --url https://eu-central-1.autoblowapi.com/vacuglide/sync-script/stop \
     --header 'x-device-token: YOUR_DEVICE_TOKEN'

PUT /vacuglide/sync-script/offset

Compensates the network latency between your player and the device. The offset stays set until you change it or the device restarts. syncScriptCurrentTime is reported without the offset.

name	required	type	description
offsetTimeMs (body)	yes	number	Offset in ms; positive means the device runs ahead of the video

curl --request PUT \
     --url https://eu-central-1.autoblowapi.com/vacuglide/sync-script/offset \
     --header 'Content-Type: application/json' \
     --header 'x-device-token: YOUR_DEVICE_TOKEN' \
     --data '{"offsetTimeMs": 100}'

PUT /vacuglide/sync-script/loop

Restarts the script from the beginning when it ends. Without looping, the device pauses at the end in SYNC_SCRIPT_PAUSED. The setting stays until you change it or the device restarts.

name	required	type	description
loop (body)	yes	bool	Whether to restart the script when it ends

curl --request PUT \
     --url https://eu-central-1.autoblowapi.com/vacuglide/sync-script/loop \
     --header 'Content-Type: application/json' \
     --header 'x-device-token: YOUR_DEVICE_TOKEN' \
     --data '{"loop": true}'

Device Events

GET /events/stream?deviceToken=...

Server-sent events for one device, served by the cluster the device is connected to. The stream opens with a connected event and sends a heartbeat every 30 seconds. While the Vacuglide is in online mode, a press on one of these buttons arrives as an event that carries no data beyond its name:

event	description
speed-plus-button-pressed	The speed plus button was pressed
speed-minus-button-pressed	The speed minus button was pressed
mode-button-pressed	The mode button was pressed briefly (holding it leaves online mode)

curl --no-buffer \
     --url 'https://eu-central-1.autoblowapi.com/events/stream?deviceToken=YOUR_DEVICE_TOKEN'

event: connected
data: {"connectionId":"bedffe18-f62e-4c9c-8e9b-7082f88d5f0c","subscribedDevice":"YOUR_DEVICE_TOKEN"}

event: mode-button-pressed
data: {"deviceToken":"YOUR_DEVICE_TOKEN","payload":{"type":"mode-button-pressed","rawData":null,"args":[]},"timestamp":1752685746276}

Device State

name	type	description
operationalMode	enum: ONLINE_CONNECTED, LOCAL_SCRIPT_PLAYING, LOCAL_SCRIPT_PAUSED, TARGET_SPEED_PLAYING, TARGET_SPEED_PAUSED, SYNC_SCRIPT_PLAYING, SYNC_SCRIPT_PAUSED, SETUP, LOADING_SETUP, LOADING_INTERACTIVE, FIRMWARE_UPDATING, ERROR, ERROR_MOTOR_STUCK, ERROR_MOTOR_OVERRUN	The current operational mode (see below)
localScript	number	Selected local script (0 to 29)
targetSpeed	number	Motor speed in percent (0 to 100), set by target-speed or by the playing script
strokePlusValve	bool	Whether the stroke plus valve is open
strokeMinusValve	bool	Whether the stroke minus valve is open
syncScriptCurrentTime	number	Script position in ms, without the offset
syncScriptOffsetTime	number	Sync offset in ms
syncScriptToken	string	Token of the loaded sync script; empty when none is loaded
syncScriptLoop	bool	Whether the sync script restarts when it ends

operationalMode	description
ONLINE_CONNECTED	Connected and idle, ready for commands
LOCAL_SCRIPT_PLAYING, LOCAL_SCRIPT_PAUSED	A local script is playing or paused
TARGET_SPEED_PLAYING, TARGET_SPEED_PAUSED	The motor runs at the target speed, or was stopped
SYNC_SCRIPT_PLAYING, SYNC_SCRIPT_PAUSED	A sync script is playing, or loaded and paused
LOADING_INTERACTIVE	Joining Wi-Fi and the cluster after the user started online mode
SETUP, LOADING_SETUP	Wi-Fi setup mode, or starting it
FIRMWARE_UPDATING	Installing a firmware update
ERROR	Generic error
ERROR_MOTOR_STUCK	The motor stopped because it is stuck
ERROR_MOTOR_OVERRUN	The motor stopped after running for 4 hours without a pause

Example (playing a sync script 24 seconds in):

{
  "operationalMode": "SYNC_SCRIPT_PLAYING",
  "localScript": 0,
  "targetSpeed": 42,
  "strokePlusValve": false,
  "strokeMinusValve": false,
  "syncScriptCurrentTime": 24000,
  "syncScriptOffsetTime": 100,
  "syncScriptToken": "7a93bfc5-4043-4ade-aee5-bec8012b0e12",
  "syncScriptLoop": false
}

Rate Limiting

Requests are limited per device token. A 429 response means the limit was hit; wait before retrying.