Skip to content
logiccloud orchestrate

Create an alert rule

POST
/api/v1/alert-rules
curl --request POST \
  --url http://localhost:3000/api/v1/alert-rules \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "name": "CPU above 80% on edge nodes", "ruleType": "DEVICE_OFFLINE", "scope": "GLOBAL", "targetId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "targetLabels": { "site": "berlin", "tier": "edge" }, "expression": "cpu > 80 AND device.label.tier = \"edge\" for 5m", "thresholdMinutes": 5, "severity": "INFO", "enabled": true, "notificationTargetIds": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ], "suppression": { "enabled": true, "trigger": "AFTER_FIRST", "maxNotifications": 1, "intervalSeconds": 1, "liftSchedule": { "type": "dailyAt", "time": "23:59" }, "liftTimezone": "UTC", "liftMode": "DIGEST" } }'

The expression is validated against the alert DSL at write time — a malformed rule is rejected here rather than silently never firing.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
x-organization-id
string format: uuid

UUID of the organization (tenant) the request acts in. It selects the tenant and grants nothing: the server checks membership or an open tenant switch. Not needed for global operations. A malformed value returns 400. API keys are fixed to their own organization; another organization returns 403. The x-organization-source header grants nothing.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name
required

Human-readable rule name

string
Example
CPU above 80% on edge nodes
ruleType
required

Condition family the rule evaluates

string
Allowed values: DEVICE_OFFLINE METRIC_THRESHOLD WORKLOAD_CRASH ROLLOUT_HALTED
Example
METRIC_THRESHOLD
scope

Which devices the rule applies to. GLOBAL covers every device in the organization; LABEL matches the selector in targetLabels; DEVICE matches the single device in targetId. ROLLOUT_HALTED rules take GLOBAL (every deployment of the organization) or DEPLOYMENT (the single deployment in targetId); the device scopes are rejected for them, and DEPLOYMENT is rejected for every other rule type.

string
default: GLOBAL
Allowed values: GLOBAL LABEL DEVICE DEPLOYMENT
targetId

Device id when scope is DEVICE, deployment id when scope is DEPLOYMENT (it must be a deployment of the caller’s organization); required for both, ignored otherwise. On PATCH, null clears it (rejected while the resulting scope needs it).

string format: uuid
nullable
targetLabels

Label selector. Required when scope is LABEL, ignored otherwise. A device matches when every key/value pair is present on its labels.

object
key
additional properties
string
Example
{
  "site": "berlin",
  "tier": "edge"
}
expression

Condition expression. Required for METRIC_THRESHOLD and WORKLOAD_CRASH; rejected for DEVICE_OFFLINE (which uses thresholdMinutes) and ROLLOUT_HALTED (which has no condition). Syntax: field op value [AND field op value ...] [for <duration>], where duration is e.g. 30s, 5m, 2h. The field vocabulary (names, units, admitted operators, allowed values) is served by GET /api/v1/alert-rules/metric-catalog; an expression naming any other field is rejected with 400 at write time.

string
Example
cpu > 80 AND device.label.tier = "edge" for 5m
thresholdMinutes

DEVICE_OFFLINE only: minutes without a heartbeat before the rule fires. Defaults to 5 per FR-FM-021.

number
default: 5 nullable >= 1 <= 1440
severity

Operator-assigned severity, carried verbatim into every notification the rule produces (email subject and body, webhook payload). Defaults to WARNING.

string
default: WARNING
Allowed values: INFO WARNING CRITICAL
enabled

Whether the rule is evaluated

boolean
default: true
notificationTargetIds

Notification targets to deliver this rule’s alerts to. Ids belonging to another organization are rejected.

Array<string>
suppression

Notification suppression for this rule (FM-1269). Omit entirely for no suppression — today’s behaviour, unchanged: every occurrence notifies.

object
enabled

Whether suppression is active for this rule. Defaults to true.

boolean
default: true
trigger

What opens the suppression window. AFTER_FIRST opens as soon as the first notification for the scope selection has pushed; RATE opens once maxNotifications have pushed within intervalSeconds. Defaults to AFTER_FIRST.

string
default: AFTER_FIRST
Allowed values: AFTER_FIRST RATE
maxNotifications

RATE trigger only: how many notifications pass per intervalSeconds before the window opens. Required together with intervalSeconds when trigger is RATE; rejected when trigger is AFTER_FIRST.

number
>= 1 <= 1000
intervalSeconds

RATE trigger only: the interval, in seconds, that the maxNotifications budget applies to. 60 seconds to 604800 seconds (one week).

number
>= 60 <= 604800
liftSchedule
required

Structured lift schedule for when the suppression window opens — NEVER a cron expression (ADR-0018-1 §2.4). Exactly one of: {“type”:“everyHours”,“hours”:1..168}, {“type”:“dailyAt”,“time”:“HH:MM”} (24-hour, zero-padded), {“type”:“weeklyAt”,“days”:[“MON”..“SUN”],“time”:“HH:MM”}. Validated against this exact shape server-side; an unknown type, a missing or extra field, or a malformed value is rejected with a 400 naming the field.

object
key
additional properties
any
Example
{
  "type": "dailyAt",
  "time": "23:59"
}
liftTimezone

IANA time zone the lift schedule is read in, e.g. Europe/Berlin or UTC. Defaults to UTC.

string
default: UTC <= 64 characters
Example
Europe/Berlin
liftMode

What the scheduled lift produces. DIGEST sends one summary notification naming every occurrence suppressed during the window (the default). REPEAT re-notifies every occurrence still open at lift time. SILENT sends nothing — the delivery history is the only record.

string
default: DIGEST
Allowed values: DIGEST REPEAT SILENT

Responses

Section titled “Responses”

201

Section titled “201”
Media typeapplication/json
object
id
required
string format: uuid
name
required
string
ruleType
required
string
Allowed values: DEVICE_OFFLINE METRIC_THRESHOLD WORKLOAD_CRASH ROLLOUT_HALTED
scope
required
string
Allowed values: GLOBAL LABEL DEVICE DEPLOYMENT
targetId
object
targetLabels
required
object
key
additional properties
string
expression
object
thresholdMinutes
object
severity
required
string
Allowed values: INFO WARNING CRITICAL
enabled
required
boolean
notificationTargets
required
Array<object>
object
id
required
string format: uuid
name
required
string
channel
required
string
enabled
required
boolean
suppression

Notification suppression for this rule (FM-1269), or null when none is set.

object
enabled
required
boolean
trigger
required
string
Allowed values: AFTER_FIRST RATE
maxNotifications

RATE trigger only. Null for AFTER_FIRST.

object
intervalSeconds

RATE trigger only. Null for AFTER_FIRST.

object
liftSchedule
required

The structured lift schedule as stored — never a cron expression. See AlertSuppressionDto.liftSchedule for the three admitted shapes.

object
key
additional properties
any
liftTimezone
required
string
liftMode
required
string
Allowed values: DIGEST REPEAT SILENT
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
Example
{
  "name": "CPU above 80% on edge nodes",
  "ruleType": "DEVICE_OFFLINE",
  "scope": "GLOBAL",
  "expression": "cpu > 80 for 5m",
  "severity": "INFO",
  "notificationTargets": [
    {
      "name": "Ops on-call email",
      "channel": "EMAIL"
    }
  ],
  "suppression": {
    "trigger": "AFTER_FIRST",
    "liftSchedule": {
      "type": "dailyAt",
      "time": "23:59"
    },
    "liftTimezone": "Europe/Berlin",
    "liftMode": "DIGEST"
  }
}

400

Section titled “400”

Malformed expression, or scope/target mismatch