Routine Trigger API

Trigger a Voice Monkey Routine Trigger device, which in turn fires the Alexa Routine you wired it into.

Endpoint

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

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

Example request

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

Or as a one-line GET, useful for IFTTT, Tasker, Flic, etc.:

curl "https://api-v3.voicemonkey.io/trigger?token=YOUR_TOKEN&device=YOUR_TRIGGER_DEVICE_ID"

Parameters

Parameter	Required	Description
token	yes	Your API token. See Authentication.
device	yes	The ID of the Routine Trigger device. List your devices with GET /devices. To fire several routines at once, give up to 10 IDs separated by commas, or a JSON array.

Response

Successful calls return 200:

{
  "success": true,
  "data": "OK"
}

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

Several routines at once

List up to 10 Routine Trigger IDs in device to fire them all in one call:

curl "https://api-v3.voicemonkey.io/trigger?token=YOUR_TOKEN&device=porch-lights-2k8d1,hall-lights-7m3q9"

Every ID is checked first, and nothing fires if one isn’t on your account. Each routine counts as one request, both against your plan and against the safety throttle. The response lists each one:

{
  "success": true,
  "data": "OK",
  "devices": [
    { "device": "porch-lights-2k8d1", "ok": true },
    { "device": "hall-lights-7m3q9", "ok": true }
  ]
}

If some fail, data is PARTIAL and each failed entry has an error. If the safety throttle, the monthly quota or the Alexa skill link stops the first one, the rest aren’t tried, and the call fails as a single-routine call would.

Setting variables in the same request

Any parameter prefixed with var- is upserted as a variable before the routine fires, so a downstream Flow that reads the variable sees the new value immediately:

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

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

Errors

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

Status	Response body	Meaning
400	{ "error": "MISSING_DEVICE" }	No device parameter supplied.
400	{ "error": "TOO_MANY_DEVICES", "max": 10 }	device lists more than 10 routines.
404	{ "error": "DEVICE_NOT_FOUND" }	The device ID isn’t on this account. When device lists several, the body also names the one that wasn’t found: { "error": "DEVICE_NOT_FOUND", "device": "<id>" }.
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": "ALEXA_TRIGGER_FAILED" }	Generic upstream Alexa failure — retry with backoff.

Use cases

• Trigger a routine from IFTTT, Zapier, Home Assistant, or any automation tool that can make an HTTP call.
• Wire a hardware button (e.g. Flic, Shelly, ESPHome) to a routine without writing custom Alexa skill code.
• Trigger a routine on a schedule from cron or a serverless function.

See Flic Buttons and Home Assistant for worked examples.