Devices API

List the devices on the authenticated account. Useful when you need to look up a device ID at runtime instead of hard-coding it, or when building tooling that targets multiple Voice Monkey accounts.

Endpoint

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

GET is the natural fit (no body, just an auth token). POST is accepted too if your client can’t easily attach a query string.

Example request

curl "https://api-v3.voicemonkey.io/devices?token=YOUR_TOKEN"

Or with the Authorization header:

curl https://api-v3.voicemonkey.io/devices \
  -H "Authorization: Bearer YOUR_TOKEN"

Parameters

Parameter	Required	Description
token	yes	Your API token. Or send it via the Authorization: Bearer … header. See Authentication.

Response

Successful calls return 200:

{
  "success": true,
  "data": [
    { "id": "kitchen-echo-3f7k2",       "name": "Kitchen Echo",       "capability": "speakers" },
    { "id": "bedroom-echo-show-9p2qb",  "name": "Bedroom Echo Show",  "capability": "speakers" },
    { "id": "living-room-lights-x4n8e", "name": "Living room lights", "capability": "routines" }
  ]
}

Field	Description
id	The device ID — pass this as device to /announce or /trigger. Generated from the name when the device is created and stable across renames.
name	The display name set in the console.
capability	speakers for Speaker devices (used with /announce), routines for Routine Trigger devices (used with /trigger).

data is [] if the account has no devices yet.

Errors

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

Status	Response body	Meaning
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.