New: the AI firewall watches the whole platform and explains each incident in plain words. See how it works

Rules API

List, create, test, change, switch on or off, run and delete Rules card rules over REST, and switch a place between Manual and Auto.

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

MethodPathPermissionDoes
GET/api/iot/rules?placeType=&placeId=&subtree=iot_rules.readThe rules of a place (and, with subtree=true on an asset, of everything under it)
GET/api/iot/rules/scope?placeType=&placeId=iot_rules.readWhat a rule of this place may name: its devices and their values, device profiles and their commands
POST/api/iot/rules/testiot_rules.readCheck a saved or unsaved rule against the values stored now; nothing runs
POST/api/iot/rulesiot_rules.manageCreate a rule
GET/api/iot/rules/{ruleId}iot_rules.readOne rule with its definition and status
PATCH/api/iot/rules/{ruleId}iot_rules.manageChange the name or the definition
DELETE/api/iot/rules/{ruleId}iot_rules.manageDelete the rule and its flow
POST/api/iot/rules/{ruleId}/enablediot_rules.manageSwitch the rule on or off
POST/api/iot/rules/{ruleId}/runiot_rules.runRun now
GET/api/iot/rules/{ruleId}/runs?limit=iot_rules.readThe latest runs, newest first
GET/api/iot/rule-modes/{placeType}/{placeId}iot_rules.readThe place’s mode
PUT/api/iot/rule-modes/{placeType}/{placeId}iot_rules.modePut the place in Manual
DELETE/api/iot/rule-modes/{placeType}/{placeId}?applyNow=trueiot_rules.modeBack to Auto

placeType is asset or device; placeId is the asset’s or the device’s id.

Permissions and API keys

PermissionDefault role
iot_rules.readUser
iot_rules.runUser
iot_rules.modeUser
iot_rules.manageAdmin

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 hasThe key also needs
A Send a command actionThe 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 commandautomation.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
  }
}
FieldMeaning
homeThe asset or device the rule belongs to. It cannot change after creation.
enabledThe rule’s own switch. It is separate from Manual: going back to Auto never switches on a rule someone switched off.
statusok, or needs_attention when a device or place it names was deleted. statusReason says why in words.
flowIdThe flow the rule runs as. It is read-only in the flow API.
updatedAtMilliseconds 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)

kindFields
valuetarget, key, change (any, above, below, equals, not_equals, between, outside), value, value2 (the top of a range), forSec (0 to 86,400)
statustarget, to (online, offline, inactive)
alarmtarget (a device reference or { "home": true }), event (raised, cleared), optional minSeverity, alarmType
timeat, optional days
everyminutes (1 to 1,440)
sunevent (sunrise, sunset), optional offsetMin (-180 to 180), days
dateat, and daysOfMonth and/or months, or days (not both daysOfMonth and days)
manualNo 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:

kindFields
valuetarget, key, op (>, >=, <, <=, ==, !=, between), value, value2
statustarget, is (online, offline)
alarmtarget (or { "home": true }), active (true or false), optional minSeverity
timeoptional after, before, days
sunis (day, night)
datemonths, daysOfMonth, and/or a window from and to (MM-DD, both or neither)
holidayis (true or false): today is a public holiday of your organisation’s calendar
exprexpr: 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)

kindFields
commandtarget, command (a method of the profile’s catalog), optional params
settingtarget, key, value
notifyrecipients (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
alarmop (raise, clear), target (or { "home": true }), alarmType, optional severity
waitsec (1 to 86,400)
wait_untilcondition, timeoutSec (1 to 86,400), onTimeout (continue, stop)
choosebranches (1 to 5 of { "if": condition, "then": [actions] }), optional else
ruleop (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

FieldValues
overlap (required)ignore, queue, parallel, restart
max1 to 10, only with queue or parallel
runInManualtrue 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

CallBodyAnswer
POST /api/iot/rules/testhomeType, 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}/runNone202 { "accepted": true, "entryId": "…" }. Conditions and Manual still apply.
GET /api/iot/rules/{ruleId}/runs?limit=20None{ "runs": [ { "at", "text", "ok" } ] }, default 20, at most 30
DELETE /api/iot/rules/{ruleId}None204

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: PUT with { "until": <milliseconds>, "reason": "…" }. Both are optional: without until, Manual lasts until someone switches it back. until must be in the future and within a year; reason is up to 500 characters. Sending it again replaces the end and the reason.
  • Auto: DELETE. With ?applyNow=true the 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 answers 409.

Errors

StatusMessage or reason
400Validation 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.”
402QUOTA_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.”
409details.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.”
422details.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

LimitValue
Name120 characters
Triggers10
Conditions in one group, nesting16, 4 levels
Actions, including those inside choices20
Branches of a choice, nesting of choices5, 2 levels
forSec, wait, wait_until24 hours
Notify recipients, text20, 1,000 characters
max runs waiting or side by side1 to 10
Run history30 runs
Manual until, reasonWithin 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.