Commands API

A command (an RPC) asks a device to do something and, unless it is one-way, waits for the device’s answer. Every command is stored as a request with a state, so you can send it now and read the result later. How commands work for people in the app is in Sending commands to devices. Paths are under https://<your host>/tenant/<tenantId>.

In development: Commands to devices behind a gateway (a gateway’s child devices) are in development. Send commands to devices that connect themselves.

Routes

Who may send what

Each command in a profile’s catalog has a tier. The tier decides the permission:

So an API key can send only methods that are in the device profile’s catalog.

Send a command

{
    "method": "pump.start",
    "params": {
        "speed": 80
    },
    "timeoutMs": 15000
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/devices/{deviceId}/rpc' \
  -H 'Content-Type: application/json' \
  -d '{"method":"pump.start","params":{"speed":80},"timeoutMs":15000}'

{
    "rpc": {
        "rpcId": "c0de…",
        "deviceId": "6f1c…",
        "method": "pump.start",
        "status": "SUCCESSFUL",
        "outcome": null,
        "response": {
            "ok": true
        },
        "error": null,
        "tier": "privileged",
        "highImpact": false,
        "source": "api",
        "createdAt": "2026-11-09T09:00:00.000Z",
        "completedAt": "2026-11-09T09:00:01.200Z",
        "…": "…"
    }
}

{
    "rpc": {
        "rpcId": "c0de…",
        "status": "QUEUED",
        "…": "…"
    }
}

{
    "message": "You are not permitted to perform this action",
    "code": "FORBIDDEN"
}

{
    "message": "The device is disabled or quarantined; it takes no commands.",
    "code": "CONFLICT",
    "details": {
        "reason": "device_not_active"
    }
}

{
    "message": "Too many commands to this device; try again in a minute.",
    "code": "RATE_LIMIT_EXCEEDED",
    "details": {
        "reason": "device_rate_limited"
    }
}

• One-way (oneway: true): the command succeeds when it is delivered; no answer is expected.
• Persistent (persistent: true): if the device is offline, the command waits for it up to expiresInS, then ends EXPIRED.
• wait: true forces waiting (refused with “A synchronous call waits at most 30 s; use wait: false for a longer timeout.” when the command cannot finish in 30 s); false always answers 202 at once.
• High-impact commands need "confirm": true, and the typed phrase in confirmText when the catalog command has one. Without it: “This command needs confirm: true.” They are written to the audit log when sent and when they end, and are sent at most once.

There is no idempotency key on this route: every POST creates a new command. If your call times out on the network, read the device’s history before you send again.

States

QUEUED → SENT → DELIVERED → SUCCESSFUL, or one of FAILED, TIMEOUT, EXPIRED, CANCELLED.

outcome adds detail: running (the device accepted a long-running command), unknown (a timeout) or late (an answer arrived after the end). Results are kept 90 days by default.

Read results

Poll GET /api/iot/rpc/{rpcId} until the state is final, or subscribe to the webhook events rpc.completed and rpc.failed and read the answer when one arrives. See the Webhook event reference.

History of one device, newest first:

GET /api/iot/devices/{deviceId}/rpc?status=FAILED&limit=50

Without page, the history is read with a cursor: status, method, from, to (dates), limit (1 to 100, default 25) and cursor. The answer is { "requests": [...], "nextCursor": "…" }; pass nextCursor back as cursor until it is null. With page (from 0), the list follows the usual list rules: pageSize, search, sort (method, status, source, createdAt, completedAt), status and source as comma lists, createdFrom, createdTo; the answer is { "requests": [...], "total": n }. Secret parameters are masked in every answer.

Cancel

POST /api/iot/rpc/{rpcId}/cancel moves a QUEUED or SENT command to CANCELLED and answers { "rpc": {...} }. Other states: 409 “Only a queued or sent request can be cancelled.” Cancelling needs the same tier permission as sending. A cancel sends no webhook.

Limits

Refusals

The command catalog

A catalog command has: method, label (up to 120), description, paramsSchema (up to 50 fields, each with label, type of text, textarea, number, boolean, select, multi-select or json, and optional required, min, max, step, options), maskedParams (secret fields never shown back), tier (basic, privileged, critical), highImpact, oneway, long, defaultTimeoutMs, persistentDefault, confirmText (high-impact only).

{
  "method": "valve.set",
  "label": "Set valve position",
  "tier": "privileged",
  "paramsSchema": { "position": { "label": "Position (%)", "type": "number", "min": 0, "max": 100, "required": true } }
}

GET ...?format=export returns { "commands": [...] } without ids, which PUT takes back to copy a catalog to another profile.