These routes let a program manage the rules of the Rules card and the Manual / Auto mode of a place. How rules behave for people is explained in The Rules card and Manual and Auto modes. The rules API is available wherever the Rules card is: it comes with Automation.
Paths are under https://<your host>/tenant/<tenantId>. Send Authorization: Bearer <API key> on every call; see Authentication and REST API basics.
Routes
| Method | Path | Permission | Does |
|---|---|---|---|
| GET | /api/iot/rules?placeType=&placeId=&subtree= | iot_rules.read | The rules of a place (and, with subtree=true on an asset, of everything under it) |
| GET | /api/iot/rules/scope?placeType=&placeId= | iot_rules.read | What a rule of this place may name: its devices and their values, device profiles and their commands |
| POST | /api/iot/rules/test | iot_rules.read | Check a saved or unsaved rule against the values stored now; nothing runs |
| POST | /api/iot/rules | iot_rules.manage | Create a rule |
| GET | /api/iot/rules/{ruleId} | iot_rules.read | One rule with its definition and status |
| PATCH | /api/iot/rules/{ruleId} | iot_rules.manage | Change the name or the definition |
| DELETE | /api/iot/rules/{ruleId} | iot_rules.manage | Delete the rule and its flow |
| POST | /api/iot/rules/{ruleId}/enabled | iot_rules.manage | Switch the rule on or off |
| POST | /api/iot/rules/{ruleId}/run | iot_rules.run | Run now |
| GET | /api/iot/rules/{ruleId}/runs?limit= | iot_rules.read | The latest runs, newest first |
| GET | /api/iot/rule-modes/{placeType}/{placeId} | iot_rules.read | The place’s mode |
| PUT | /api/iot/rule-modes/{placeType}/{placeId} | iot_rules.mode | Put the place in Manual |
| DELETE | /api/iot/rule-modes/{placeType}/{placeId}?applyNow=true | iot_rules.mode | Back to Auto |
placeType is asset or device; placeId is the asset’s or the device’s id.
Permissions and API keys
| Permission | Default role |
|---|---|
iot_rules.read | User |
iot_rules.run | User |
iot_rules.mode | User |
iot_rules.manage | Admin |
An API key can hold all four. Every call also needs access to the place the rule or the mode is about, so your access policies can narrow which places a key reaches.
A rule is saved as a flow deployed in the name of the key’s member, so the key must also be allowed to do what the rule does:
| The rule has | The key also needs |
|---|---|
| A Send a command action | The send permission of each tier the command has in the device profile’s catalog (iot_rpc.send.basic, iot_rpc.send.privileged, iot_rpc.send.critical) |
| A high-impact command | automation.manage_privileged as well |
The key does not need automation.manage to save a rule. Without a needed permission, saving answers 403 “You do not hold the permission this rule needs: …”, with the missing ids in details.missing. See Commands API for tiers.
The rule object
{
"rule": {
"ruleId": "3c4d…",
"home": { "type": "asset", "id": "a1b2…" },
"name": "Fan on when hot",
"enabled": true,
"definition": { "v": 1, "when": [], "then": [], "options": { "overlap": "ignore" } },
"status": "ok",
"statusReason": null,
"flowId": "9e8f…",
"updatedAt": 1762678800000
}
}
| Field | Meaning |
|---|---|
home | The asset or device the rule belongs to. It cannot change after creation. |
enabled | The rule’s own switch. It is separate from Manual: going back to Auto never switches on a rule someone switched off. |
status | ok, or needs_attention when a device or place it names was deleted. statusReason says why in words. |
flowId | The flow the rule runs as. It is read-only in the flow API. |
updatedAt | Milliseconds since the epoch |
The list GET /api/iot/rules answers { "rules": [...], "can": {...} }. Each row adds lastRun ({ at, text, ok } or null) and nextAt (the next start in milliseconds for a rule with a time, date or sun trigger, else null). can says what the caller may do here: manage, run, mode and sendCommands, each true or false.
The definition
A definition has four parts. Unknown fields are refused everywhere.
{
"v": 1,
"when": [ { "id": "hot", "kind": "value", "target": { "device": "6f1c…" }, "key": "temperature", "change": "above", "value": 28, "forSec": 300 } ],
"onlyIf": { "kind": "time", "after": "08:00", "before": "18:00", "days": [1, 2, 3, 4, 5] },
"then": [ { "id": "fan", "kind": "command", "target": { "device": "7a2d…" }, "command": "fan.on" } ],
"options": { "overlap": "ignore" }
}
Every trigger and action has an id: lower-case letters, digits, - and _, up to 24 characters, unique in the rule. A device reference is { "device": "<deviceId>" } for one device or { "deviceType": "<deviceProfileId>" } for every device of that profile in the home’s scope. Weekdays are 1 (Monday) to 7 (Sunday). Times are HH:MM in the home’s time zone. Severities are lower case: critical, major, minor, warning, info.
When (1 to 10 triggers, any of them starts the rule)
kind | Fields |
|---|---|
value | target, key, change (any, above, below, equals, not_equals, between, outside), value, value2 (the top of a range), forSec (0 to 86,400) |
status | target, to (online, offline, inactive) |
alarm | target (a device reference or { "home": true }), event (raised, cleared), optional minSeverity, alarmType |
time | at, optional days |
every | minutes (1 to 1,440) |
sun | event (sunrise, sunset), optional offsetMin (-180 to 180), days |
date | at, and daysOfMonth and/or months, or days (not both daysOfMonth and days) |
manual | No fields: the rule starts only by Run now |
Only if (optional, one condition)
A condition is a group, { "all": [...] }, { "any": [...] } or { "not": {...} }, or one of these:
kind | Fields |
|---|---|
value | target, key, op (>, >=, <, <=, ==, !=, between), value, value2 |
status | target, is (online, offline) |
alarm | target (or { "home": true }), active (true or false), optional minSeverity |
time | optional after, before, days |
sun | is (day, night) |
date | months, daysOfMonth, and/or a window from and to (MM-DD, both or neither) |
holiday | is (true or false): today is a public holiday of your organisation’s calendar |
expr | expr: a formula, up to 500 characters |
The meaning of each is in Rules card: conditions and Time, sunrise/sunset, dates and holidays.
Then (1 to 20 actions, in order)
kind | Fields |
|---|---|
command | target, command (a method of the profile’s catalog), optional params |
setting | target, key, value |
notify | recipients (1 to 20 of { "kind": "user", "userId" }, { "kind": "role", "role": "OWNER" } (or ADMIN, USER), { "kind": "team", "teamId" }), text (up to 1,000 characters), optional channels |
alarm | op (raise, clear), target (or { "home": true }), alarmType, optional severity |
wait | sec (1 to 86,400) |
wait_until | condition, timeoutSec (1 to 86,400), onTimeout (continue, stop) |
choose | branches (1 to 5 of { "if": condition, "then": [actions] }), optional else |
rule | op (enable, disable, run), rule (another rule’s id). run must be the last step. |
What each action does is in Rules card: actions; channels is explained in Notifications from rules and flows.
Options
| Field | Values |
|---|---|
overlap (required) | ignore, queue, parallel, restart |
max | 1 to 10, only with queue or parallel |
runInManual | true only for a rule without commands, settings or rule actions |
Create a rule
POST /api/iot/rules with homeType, homeId, name (1 to 120 characters), definition, and optionally enabled (default true) and confirmed.
A rule that acts on its own, for example one that sends commands or changes settings, must be confirmed. Without "confirmed": true such a rule answers 409 with details.needsConfirmation: true and the reasons in details.reasons, the same confirmation the card asks for. Send it again with "confirmed": true. Sending confirmed on every save of a rule you mean to act is safe.
curl -X POST "https://<your host>/tenant/<tenantId>/api/iot/rules" \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"homeType":"asset","homeId":"a1b2…","name":"Fan on when hot","confirmed":true,"definition":{"v":1,"when":[{"id":"hot","kind":"value","target":{"device":"6f1c…"},"key":"temperature","change":"above","value":28,"forSec":300}],"then":[{"id":"fan","kind":"command","target":{"device":"7a2d…"},"command":"fan.on"}],"options":{"overlap":"ignore"}}}'
The answer is 201 { "rule": {...} }. A definition with problems answers 422 with each problem and the path of its row:
{
"message": "Type the value to compare with.",
"code": "VALIDATION_ERROR",
"details": { "problems": [ { "path": ["when", 0, "value"], "code": "value_missing", "message": "Type the value to compare with." } ] }
}
Read GET /api/iot/rules/scope first to learn the device ids, value keys and catalog commands of the place. A rule may name only devices in its home’s scope.
Test, change, switch, run and delete
| Call | Body | Answer |
|---|---|---|
POST /api/iot/rules/test | homeType, homeId, definition, optional name | { "result": { "triggers", "conditions", "actions", "mode", "wouldRun", "summary" } }. Nothing is sent or written. |
PATCH /api/iot/rules/{ruleId} | name and/or definition, optional confirmed | { "rule": {...} }. The same checks as a create. |
POST /api/iot/rules/{ruleId}/enabled | { "enabled": true }, optional confirmed | { "rule": {...} } |
POST /api/iot/rules/{ruleId}/run | None | 202 { "accepted": true, "entryId": "…" }. Conditions and Manual still apply. |
GET /api/iot/rules/{ruleId}/runs?limit=20 | None | { "runs": [ { "at", "text", "ok" } ] }, default 20, at most 30 |
DELETE /api/iot/rules/{ruleId} | None | 204 |
A rule in needs_attention cannot be switched on or run until it is saved again with a valid definition.
Manual and Auto
GET /api/iot/rule-modes/{placeType}/{placeId} answers:
{ "mode": { "mode": "auto", "effective": "manual", "setOn": { "type": "asset", "id": "a1b2…" }, "until": 1762686000000, "setBy": "5d6e…", "setAt": 1762678800000, "reason": "Pump service" } }
mode is what the place itself is set to; effective is what applies, Manual when the place or an asset above it is Manual; setOn names that asset.
- Manual:
PUTwith{ "until": <milliseconds>, "reason": "…" }. Both are optional: withoutuntil, Manual lasts until someone switches it back.untilmust be in the future and within a year;reasonis up to 500 characters. Sending it again replaces the end and the reason. - Auto:
DELETE. With?applyNow=truethe rules of the place and everything under it start again from the values stored now; the answer{ "mode": {...}, "rearmed": n }counts what was woken. A place that follows Manual from an asset above answers409.
Errors
| Status | Message or reason |
|---|---|
| 400 | Validation error with issues: a field the route does not know, or a value of the wrong shape. “Choose an end in the future, within a year.” |
| 402 | QUOTA_EXCEEDED: saving the rule would go over a plan limit; details.key names the limit and details.limit its value |
| 403 | “You do not hold the permission this rule needs: …” (details.missing), or the key or its member may not use the route or the place |
| 404 | “This rule was not found.” / “This place was not found.” / “This device was not found.” |
| 409 | details.needsConfirmation: send confirmed: true. “This rule is switched off; switch it on to run it.” “This rule needs attention before it can run.” “The rule changed while you were editing it; reload it and save again.” “This place follows a place above it that is in Manual; switch that one to Auto.” |
| 422 | details.problems: the definition cannot be saved. Codes include value_missing, range_missing, duplicate_id, device_out_of_scope, too_many_devices, bad_param, run_not_last, self_reference, run_in_manual_with_equipment, max_without_queue. |
| 503 | “No worker is running the rules right now, so the rule would not start.” (Run now) |
The general error body and the rate limits are in Errors and rate limits.
Limits
| Limit | Value |
|---|---|
| Name | 120 characters |
| Triggers | 10 |
| Conditions in one group, nesting | 16, 4 levels |
| Actions, including those inside choices | 20 |
| Branches of a choice, nesting of choices | 5, 2 levels |
forSec, wait, wait_until | 24 hours |
| Notify recipients, text | 20, 1,000 characters |
max runs waiting or side by side | 1 to 10 |
| Run history | 30 runs |
Manual until, reason | Within a year, 500 characters |
Rules count against your plan’s rule limit, not its flow limit. The other limits (devices in a scope, devices one row acts on) are on The Rules card.
Events instead of polling
Subscribe a webhook to rules.mode_changed (a place switched to Manual, back to Auto, or its Manual ended) and rules.needs_attention (a rule was switched off because something it names is gone). Payloads are in the Webhook event reference.

