Flows API

Start a Flow by its request reference, optionally setting variables in the same call.

Endpoint

GET/POST https://api-v3.voicemonkey.io/flow

POST and GET behave identically — pick whichever your HTTP client makes easiest.

Example request

curl -X POST https://api-v3.voicemonkey.io/flow \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_TOKEN",
    "flow": "1234"
  }'

Or as a one-line GET:

curl "https://api-v3.voicemonkey.io/flow?token=YOUR_TOKEN&flow=1234"

Parameters

Parameter	Required	Description
token	yes	Your API token. See Authentication.
flow	yes	The Flow’s request reference — a short code (e.g. 1234) shown on each flow card on the Flows list and on the Flow edit page. The request reference is the public handle; internal Flow IDs aren’t accepted as input.
device	no	Override the device the Flow runs against. Defaults to the first device referenced inside the Flow’s nodes.
var-<NAME>	no	Upsert a variable before the Flow walks its nodes. Repeat for as many variables as you need.

Device resolution

If you don’t supply device, the Flow runs against the first device it encounters when walking its nodes (typically the device on the first speech / audio / video / image node). If your Flow doesn’t reference any device explicitly — for example a pure Routine Trigger or Web Request flow — the request still succeeds, the Flow just runs without a target device.

If you do supply device, it must be a device on your account; otherwise the call returns 404 DEVICE_NOT_FOUND.

Setting variables in the same request

Any parameter prefixed with var- is upserted as a variable before the Flow walks its nodes, so condition nodes and {NAME} placeholders inside speech see the value you just sent:

curl -X POST https://api-v3.voicemonkey.io/flow \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_TOKEN",
    "flow": "1234",
    "var-FIRST_NAME": "Joe",
    "var-CAMERA_STATUS": "motion"
  }'

See Variables API → Setting variables alongside any other API call for the full rules.

Response

Successful calls return 200:

{
  "success": true,
  "data": {
    "flowId": "...",
    "flowName": "Front door motion",
    "requestRef": "1234"
  }
}

If any var- sidecar updates ran, the response also includes a variableUpdates array.

Errors

Errors return a JSON body with an error field and an HTTP status code:

Status	Response body	Meaning
400	{ "error": "MISSING_FLOW" }	No flow parameter supplied.
404	{ "error": "FLOW_NOT_FOUND" }	No Flow matches that request reference on this account.
400	{ "error": "FLOW_DISABLED" }	The Flow exists but has been disabled in the console. Re-enable it on the Flows list.
404	{ "error": "DEVICE_NOT_FOUND" }	A device override was supplied but isn’t on this account.
401	{ "error": "UNAUTHORIZED" }	No token supplied.
401	{ "error": "INVALID_TOKEN" }	Token doesn’t match an active token.
429	{ "error": "THROTTLED", "lockoutUntil": "<ISO>" }	Per-user safety lockout — back off until the timestamp.
429	{ "error": "MONTHLY_QUOTA_EXCEEDED", "periodEnd": "<ISO>" }	Plan’s monthly request budget exhausted. Wait for the period end or upgrade.
500	{ "error": "FLOW_TRIGGER_FAILED" }	Generic flow execution failure — retry with backoff and check the Activity Log.

Tips

• Setting var-<NAME> parameters is the cleanest way to parameterise a Flow for different callers (e.g. per-room announcements from a single Flow).
• Need to fetch a variable’s current value from the Flow caller’s side? Use GET /variables.
• Flow runs are visible in the Activity Log in the console — useful when debugging condition branches.