Skip to content
Fleet Manager

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, "enabled": true, "notificationTargetIds": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ] }'

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”

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
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.

string
default: GLOBAL
Allowed values: GLOBAL LABEL DEVICE
targetId

Device id. Required when scope is DEVICE, ignored otherwise.

string format: uuid
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; ignored for DEVICE_OFFLINE, which uses thresholdMinutes. Syntax: field op value [AND field op value ...] [for <duration>], where duration is e.g. 30s, 5m, 2h. Fields: cpu, memory, disk (percentages), restarts, containersFailed, containersRunning, errors, uptime, device.status, device.name, device.label..

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 >= 1 <= 1440
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>

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
scope
required
string
Allowed values: GLOBAL LABEL DEVICE
targetId
object
targetLabels
required
object
key
additional properties
string
expression
object
thresholdMinutes
object
enabled
required
boolean
notificationTargets
required
Array<object>
object
id
required
string format: uuid
name
required
string
channel
required
string
enabled
required
boolean
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",
  "notificationTargets": [
    {
      "name": "Ops on-call email",
      "channel": "EMAIL"
    }
  ]
}

400

Section titled “400”

Malformed expression, or scope/target mismatch