Ces routes permettent à un programme de gérer les règles de la carte Règles et le mode Manuel / Auto d’un lieu. Le fonctionnement des règles pour les utilisateurs est expliqué dans La carte Règles et Modes Manuel et Auto. L’API des règles est disponible partout où se trouve la carte Règles : elle est incluse dans Automation.
Les chemins se trouvent sous https://<your host>/tenant/<tenantId>. Envoyez Authorization: Bearer <API key> à chaque appel ; voir Authentification et Bases de l’API REST.
Routes
| Méthode | Chemin | Permission | Fonction |
|---|---|---|---|
| GET | /api/iot/rules?placeType=&placeId=&subtree= | iot_rules.read | Les règles d’un lieu (et, avec subtree=true sur un actif, de tout ce qui se trouve en dessous) |
| GET | /api/iot/rules/scope?placeType=&placeId= | iot_rules.read | Ce qu’une règle de ce lieu peut citer : ses appareils et leurs valeurs, les profils d’appareils et leurs commandes |
| POST | /api/iot/rules/test | iot_rules.read | Vérifie une règle enregistrée ou non enregistrée par rapport aux valeurs stockées actuellement ; rien ne s’exécute |
| POST | /api/iot/rules | iot_rules.manage | Créer une règle |
| GET | /api/iot/rules/{ruleId} | iot_rules.read | Une règle avec sa définition et son statut |
| PATCH | /api/iot/rules/{ruleId} | iot_rules.manage | Modifie le nom ou la définition |
| DELETE | /api/iot/rules/{ruleId} | iot_rules.manage | Supprime la règle et son flux |
| POST | /api/iot/rules/{ruleId}/enabled | iot_rules.manage | Active ou désactive la règle |
| POST | /api/iot/rules/{ruleId}/run | iot_rules.run | Exécuter maintenant |
| GET | /api/iot/rules/{ruleId}/runs?limit= | iot_rules.read | Les dernières exécutions, les plus récentes en premier |
| GET | /api/iot/rule-modes/{placeType}/{placeId} | iot_rules.read | Le mode du lieu |
| PUT | /api/iot/rule-modes/{placeType}/{placeId} | iot_rules.mode | Passe le lieu en Manuel |
| DELETE | /api/iot/rule-modes/{placeType}/{placeId}?applyNow=true | iot_rules.mode | Retour en Auto |
placeType vaut asset ou device ; placeId est l’identifiant de l’actif ou de l’appareil.
Permissions et clés API
| Permission | Rôle par défaut |
|---|---|
iot_rules.read | Utilisateur |
iot_rules.run | Utilisateur |
iot_rules.mode | Utilisateur |
iot_rules.manage | Administrateur |
Une clé API peut détenir les quatre. Chaque appel nécessite aussi l’accès au lieu concerné par la règle ou le mode, de sorte que vos politiques d’accès peuvent restreindre les lieux auxquels une clé accède.
Une règle est enregistrée comme un flux déployé au nom du membre de la clé ; la clé doit donc aussi être autorisée à faire ce que fait la règle :
| La règle comporte | La clé a aussi besoin de |
|---|---|
| Une action Envoyer une commande | La permission d’envoi de chaque niveau que la commande possède dans le catalogue du profil d’appareil (iot_rpc.send.basic, iot_rpc.send.privileged, iot_rpc.send.critical) |
| Une commande à fort impact | automation.manage_privileged également |
La clé n’a pas besoin de automation.manage pour enregistrer une règle. Sans une permission nécessaire, l’enregistrement répond 403 « Vous ne détenez pas la permission dont cette règle a besoin : … », avec les identifiants manquants dans details.missing. Voir API des commandes pour les niveaux.
L’objet règle
{
"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
}
}
| Champ | Signification |
|---|---|
home | L’actif ou l’appareil auquel la règle appartient. Il ne peut pas être modifié après la création. |
enabled | L’interrupteur propre à la règle. Il est distinct du mode Manuel : repasser en Auto n’active jamais une règle désactivée par quelqu’un. |
status | ok, ou needs_attention lorsqu’un appareil ou un lieu qu’elle cite a été supprimé. statusReason explique pourquoi, en mots. |
flowId | Le flux dans lequel la règle s’exécute. Il est en lecture seule dans l’API des flux. |
updatedAt | Millisecondes depuis l’époque |
La liste GET /api/iot/rules répond { "rules": [...], "can": {...} }. Chaque ligne ajoute lastRun ({ at, text, ok } ou null) et nextAt (le prochain démarrage en millisecondes pour une règle avec un déclencheur horaire, de date ou solaire, sinon null). can indique ce que l’appelant peut faire ici : manage, run, mode et sendCommands, chacun à true ou false.
La définition
Une définition comporte quatre parties. Les champs inconnus sont refusés partout.
{
"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" }
}
Chaque déclencheur et chaque action a un id : lettres minuscules, chiffres, - et _, jusqu’à 24 caractères, unique dans la règle. Une référence d’appareil est { "device": "<deviceId>" } pour un appareil, ou { "deviceType": "<deviceProfileId>" } pour chaque appareil de ce profil dans le périmètre du site. Les jours de la semaine vont de 1 (lundi) à 7 (dimanche). Les heures sont au format HH:MM dans le fuseau horaire du site. Les gravités sont en minuscules : critical, major, minor, warning, info.
Quand (1 à 10 déclencheurs, il suffit qu’un seul démarre la règle)
kind | Champs |
|---|---|
value | target, key, change (any, above, below, equals, not_equals, between, outside), value, value2 (la borne haute d’une plage), forSec (0 à 86 400) |
status | target, to (online, offline, inactive) |
alarm | target (une référence d’appareil ou { "home": true }), event (raised, cleared), minSeverity optionnel, alarmType |
time | at, days optionnel |
every | minutes (1 à 1 440) |
sun | event (sunrise, sunset), offsetMin optionnel (-180 à 180), days |
date | at, et daysOfMonth et/ou months, ou days (pas à la fois daysOfMonth et days) |
manual | Aucun champ : la règle ne démarre que par Exécuter maintenant |
Seulement si (facultatif, une condition)
Une condition est un groupe, { "all": [...] }, { "any": [...] } ou { "not": {...} }, ou l’une de celles-ci :
kind | Champs |
|---|---|
value | target, key, op (>, >=, <, <=, ==, !=, between), value, value2 |
status | target, is (online, offline) |
alarm | target (ou { "home": true }), active (true ou false), minSeverity optionnel |
time | after, before, days optionnels |
sun | is (day, night) |
date | months, daysOfMonth, et/ou une fenêtre from et to (MM-DD, les deux ou aucun) |
holiday | is (true ou false) : aujourd’hui est un jour férié du calendrier de votre organisation |
expr | expr : une formule, jusqu’à 500 caractères |
La signification de chacun figure dans Carte Règles : conditions et Heure, lever/coucher du soleil, dates et jours fériés.
Alors (1 à 20 actions, dans l’ordre)
kind | Champs |
|---|---|
command | target, command (une méthode du catalogue du profil), params facultatif |
setting | target, key, value |
notify | recipients (de 1 à 20 de { "kind": "user", "userId" }, { "kind": "role", "role": "OWNER" } (ou ADMIN, USER), { "kind": "team", "teamId" }), text (jusqu’à 1 000 caractères), channels facultatif |
alarm | op (raise, clear), target (ou { "home": true }), alarmType, severity facultatif |
wait | sec (de 1 à 86 400) |
wait_until | condition, timeoutSec (de 1 à 86 400), onTimeout (continue, stop) |
choose | branches (de 1 à 5 de { "if": condition, "then": [actions] }), else facultatif |
rule | op (enable, disable, run), rule (l’identifiant d’une autre règle). run doit être la dernière étape. |
Ce que fait chaque action est décrit dans Rules card : actions ; channels est expliqué dans Notifications from rules and flows.
Options
| Champ | Valeurs |
|---|---|
overlap (obligatoire) | ignore, queue, parallel, restart |
max | de 1 à 10, uniquement avec queue ou parallel |
runInManual | true uniquement pour une règle sans commandes, réglages ni actions de règle |
Créer une règle
POST /api/iot/rules avec homeType, homeId, name (de 1 à 120 caractères), definition, et éventuellement enabled (par défaut true) et confirmed.
Une règle qui agit d’elle-même, par exemple une règle qui envoie des commandes ou modifie des réglages, doit être confirmée. Sans "confirmed": true, une telle règle répond 409 avec details.needsConfirmation: true et les motifs dans details.reasons, soit la même confirmation que celle demandée par la carte. Renvoyez-la avec "confirmed": true. Envoyer confirmed à chaque enregistrement d’une règle que vous destinez à agir est sans risque.
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"}}}'
La réponse est 201 { "rule": {...} }. Une définition comportant des problèmes répond 422 avec chaque problème et le chemin de sa ligne :
{
"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." } ] }
}
Lisez d’abord GET /api/iot/rules/scope pour connaître les identifiants des appareils, les clés de valeur et les commandes du catalogue du lieu. Une règle ne peut nommer que des appareils présents dans le périmètre de son site.
Tester, modifier, activer, exécuter et supprimer
| Appel | Corps | Réponse |
|---|---|---|
POST /api/iot/rules/test | homeType, homeId, definition, name facultatif | { "result": { "triggers", "conditions", "actions", "mode", "wouldRun", "summary" } }. Rien n’est envoyé ni écrit. |
PATCH /api/iot/rules/{ruleId} | name et/ou definition, confirmed facultatif | { "rule": {...} }. Mêmes contrôles qu’à la création. |
POST /api/iot/rules/{ruleId}/enabled | { "enabled": true }, confirmed facultatif | { "rule": {...} } |
POST /api/iot/rules/{ruleId}/run | Aucun | 202 { "accepted": true, "entryId": "…" }. Les conditions et le mode Manuel s’appliquent toujours. |
GET /api/iot/rules/{ruleId}/runs?limit=20 | Aucun | { "runs": [ { "at", "text", "ok" } ] }, 20 par défaut, 30 au maximum |
DELETE /api/iot/rules/{ruleId} | Aucun | 204 |
Une règle en needs_attention ne peut être ni activée ni exécutée tant qu’elle n’a pas été enregistrée à nouveau avec une définition valide.
Manuel et Auto
GET /api/iot/rule-modes/{placeType}/{placeId} répond :
{ "mode": { "mode": "auto", "effective": "manual", "setOn": { "type": "asset", "id": "a1b2…" }, "until": 1762686000000, "setBy": "5d6e…", "setAt": 1762678800000, "reason": "Pump service" } }
mode est le réglage du lieu lui-même ; effective est celui qui s’applique, Manuel lorsque le lieu ou un actif au-dessus de lui est en Manuel ; setOn désigne cet actif.
- Manuel :
PUTavec{ "until": <millisecondes>, "reason": "…" }. Les deux champs sont facultatifs : sansuntil, le mode Manuel reste actif jusqu’à ce que quelqu’un le repasse en Auto.untildoit être dans le futur et à moins d’un an ;reasoncomporte jusqu’à 500 caractères. Un nouvel envoi remplace la fin et le motif. - Auto :
DELETE. Avec?applyNow=true, les règles du lieu et de tout ce qui se trouve dessous repartent à partir des valeurs stockées à cet instant ; la réponse{ "mode": {...}, "rearmed": n }compte ce qui a été réveillé. Un lieu qui suit le mode Manuel d’un actif au-dessus répond409.
Erreurs
| Statut | Message ou motif |
|---|---|
| 400 | Validation error avec issues : un champ inconnu de la route, ou une valeur de forme incorrecte. « Choisissez une fin dans le futur, à moins d’un an. » |
| 402 | QUOTA_EXCEEDED : l’enregistrement de la règle dépasserait une limite de votre offre ; details.key désigne la limite et details.limit sa valeur |
| 403 | « Vous ne disposez pas de l’autorisation nécessaire à cette règle : … » (details.missing), ou la clé ou son membre ne peut pas utiliser cette route ou ce lieu |
| 404 | « Cette règle est introuvable. » / « Ce lieu est introuvable. » / « Cet appareil est introuvable. » |
| 409 | details.needsConfirmation : envoyez confirmed: true. « Cette règle est désactivée ; activez-la pour l’exécuter. » « Cette règle doit être vérifiée avant de pouvoir être exécutée. » « La règle a été modifiée pendant votre édition ; rechargez-la et enregistrez à nouveau. » « Ce lieu suit un lieu au-dessus de lui qui est en Manuel ; passez celui-ci en Auto. » |
| 422 | details.problems : la définition ne peut pas être enregistrée. Les codes incluent 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 | « Aucun worker n’exécute les règles pour le moment, la règle ne démarrerait donc pas. » (Exécuter maintenant) |
Le corps d’erreur général et les limites de débit sont décrits dans Errors and rate limits.
Limites
| Limite | Valeur |
|---|---|
| Nom | 120 caractères |
| Déclencheurs | 10 |
| Conditions dans un groupe, imbrication | 16, 4 niveaux |
| Actions, y compris celles figurant dans des choix | 20 |
| Branches d’un choix, imbrication des choix | 5, 2 niveaux |
forSec, wait, wait_until | 24 heures |
| Destinataires de la notification, texte | 20, 1 000 caractères |
max exécutions en attente ou en parallèle | 1 à 10 |
| Historique d’exécution | 30 exécutions |
Manuel : until, reason | Moins d’un an, 500 caractères |
Les règles comptent dans la limite de règles de votre offre, et non dans sa limite de flux. Les autres limites (appareils d’un périmètre, appareils qu’une ligne pilote) figurent sur The Rules card.
Événements au lieu d’interrogation
Abonnez un webhook à rules.mode_changed (un lieu passé en Manuel, repassé en Auto, ou dont le mode Manuel a pris fin) et à rules.needs_attention (une règle désactivée parce qu’un élément qu’elle nomme n’existe plus). Les charges utiles sont décrites dans la Webhook event reference.

