Interpret free text into a command and send it

Runs text against this device's (or, with target set, a sub-device's) own command catalog through an LLM, then dispatches whatever command it resolves through the exact same path POST .../command uses - same DeviceGrant check, same approval flow, same everything. If the text doesn't clearly resolve to one catalog command, nothing is sent - the response comes back with ok: false and a reply you can show the caller instead. Meant for building a chat-style interface on top of the API; the strict/structured way to send a command is still POST .../command.

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.

text*string

Free-text instruction, interpreted against this device's (or sub-device's, if target is set) own command catalog. Not guaranteed to resolve - see the response's "reply" and "interpreted" fields.

Length1 <= length <= 500

target?string

A sub-device ID behind this device to interpret and dispatch against instead of the device itself.

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/devices/string/nl-command" \  -H "Content-Type: application/json" \  -d '{    "text": "turn the porch light on"  }'

{  "ok": true,  "reply": "Turning the porch light on.",  "interpreted": {    "cmd": "ON",    "params": null,    "confidence": "high"  }}

Interpret free text into a command and send it

Authorization

Path Parameters

Request Body

Response Body

200application/json

400application/json

403application/json

404application/json

502application/json

Example Sent

Example Nothing matched

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`