Send a command to a device

The general-purpose command endpoint - validates the command and its params against the device's catalog, checks the caller's DeviceGrant, then either publishes it over MQTT immediately or (for a command marked requiresApproval) creates a pending approval instead of executing it. An API key needs a DeviceGrant covering this device and this command name - see the Authentication & Access guide.

How to use this: first call GET /devices/{deviceId}/commands to see exactly which cmd values this device accepts and what params (if any) each one expects, then send one of those cmd names here. A plain relay with no custom command catalog accepts "ON", "OFF", "TOGGLE", and "STATUS" with no params at all.

Authorization

X-Api-Key<token>

A secret API key created on the dashboard (API Keys page). By itself it grants nothing - it must also have a DeviceGrant scoping it to the specific device(s) and command(s) it may call.

In: header

Path Parameters

deviceId*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

cmd*string

A command name from this device's catalog - see GET /devices/{deviceId}/commands for the exact names this specific device accepts. Devices with no custom command catalog accept the legacy "ON"/"OFF"/"TOGGLE"/"STATUS" set.

Length1 <= length <= 64

params?

Only include this if the command you're sending declares a paramsSchema in its catalog entry (e.g. SET_BRIGHTNESS might expect { "level": 60 }). Omit entirely for a command that takes no arguments, like plain ON/OFF.

queuedAt?number

Unix milliseconds. Optional - set this if your own app queued this command locally (e.g. while offline) before actually sending it, so Nexalware can reject it with COMMAND_EXPIRED if it sat for more than 5 minutes, instead of firing a stale command late. Omit it for a command sent immediately - it is never required.

target?string

Only set this if this device is a "master" orchestrating other physical devices locally (see the Device Orchestration docs) and you want to command one specific sub-device instead of the master itself. Omit for a normal command aimed at this device.

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/devices/string/command" \  -H "Content-Type: application/json" \  -d '{    "cmd": "ON"  }'

{  "ok": true}

Authorization

Path Parameters

Request Body

Response Body

200application/json

202application/json

400application/json

403application/json

404application/json

409application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`