Alert Rules Operations Create
Create a new Alert Rule and its delivery destination. Requires ADMIN or SECURITY_OPERATOR.
The new alert rule: its name, the trigger condition (trigger, or triggerType with triggerValue), and the optional scope, threshold, delivery destination (deliveryType and recipient) and enabled flag. name is required.
Show optional properties
{
"name": "string"
}
{
"name": "Repeated blocked actions in Production",
"trigger": "Outcome = Enforced (blocked)",
"triggerType": "OUTCOME",
"triggerValue": "PREVENTED",
"scope": "Production Servers",
"groupScopeId": 1,
"threshold": "5 in 5 minutes",
"thresholdCount": 5,
"thresholdWindow": "FIVE_MINUTES",
"delivery": "Email · [email protected]",
"deliveryType": "EMAIL",
"recipient": "[email protected]",
"enabled": true
}
Name of the new Alert Rule. Required; stored trimmed, at most 255 characters, and no other Alert Rule may have the same name
Display trigger string or canonical condition label
Supported architectural trigger classification for Alert Rules
OUTCOME: The rule fires on events with a given outcome (ALLOWED, DETECTED_OBSERVE, PREVENTED, TERMINATED or ERROR)EVENT_CLASS: The rule fires on events of a given class (EXEC, FILE, NET, CONFIG, BEHAVIORAL or TAMPER)EVENT_CATEGORY: The rule fires on events of a given category (PROCESS_EXECUTION, FILE, NETWORK or SYSTEM_CALL)LICENSE_EXPIRY: The built-in license expiration rule. It is not event-driven: its alerts are created by the licensing scheduler, the event engine never evaluates it, and a rule cannot be created or retargeted to this type
Canonical trigger literal
Target scope string (e.g. All Hypervisors, All Groups)
Target Security Group ID (optional, null for fleet-wide)
Threshold expression (e.g. 'Any occurrence' or '5 in 1 minute')
Threshold count (>= 1)
Evaluation lookback window for threshold breach detection
ANY_OCCURRENCE: No fixed period: a single matching event qualifies. The default of a rule; the engine looks back only a short period derived from its sweep interval, at least 10 secondsONE_MINUTE: Matching events are counted over a 60-second lookback; a threshold text such as 5 in 1 minute selects it when the stated minutes are below 5FIVE_MINUTES: Matching events are counted over a 300-second lookback; a threshold text selects it when the stated minutes are 5 or more
Outbound delivery notification channel
EMAIL: Notifications go to an email address, which must be a valid email address; chosen when the recipient contains @ and no channel is givenWEBHOOK: Notifications go to an http or https URL with a host that is not a loopback or unspecified address; chosen when the recipient starts with http:// or https:// and no channel is given
Delivery destination (email address or webhook URL)
Whether the rule is enabled initially
201 Created successful response envelope. The created alert rule with its delivery destination
{
"id": "5",
"alertRuleId": 5,
"name": "Repeated blocked actions in Production",
"trigger": "Outcome = Enforced (blocked)",
"triggerType": "OUTCOME",
"triggerValue": "PREVENTED",
"scope": "Production Servers",
"groupScopeId": 1,
"threshold": "5 in 5 minutes",
"thresholdCount": 5,
"thresholdWindow": "FIVE_MINUTES",
"delivery": "Email · [email protected]",
"deliveryType": "EMAIL",
"recipient": "[email protected]",
"enabled": true,
"revision": 1,
"ruleSource": "CUSTOM",
"systemKey": null,
"createdAt": "2026-01-16T10:00:00Z",
"updatedAt": "2026-01-16T10:00:00Z"
}
String identifier matching frontend requirements
Unique canonical Alert Rule identifier
Human-readable rule name
Display-friendly trigger label (e.g. Outcome = Enforced (blocked))
Supported architectural trigger classification for Alert Rules
OUTCOME: The rule fires on events with a given outcome (ALLOWED, DETECTED_OBSERVE, PREVENTED, TERMINATED or ERROR)EVENT_CLASS: The rule fires on events of a given class (EXEC, FILE, NET, CONFIG, BEHAVIORAL or TAMPER)EVENT_CATEGORY: The rule fires on events of a given category (PROCESS_EXECUTION, FILE, NETWORK or SYSTEM_CALL)LICENSE_EXPIRY: The built-in license expiration rule. It is not event-driven: its alerts are created by the licensing scheduler, the event engine never evaluates it, and a rule cannot be created or retargeted to this type
Canonical trigger value matching schema enums
Display scope label (e.g. All Hypervisors or group name)
Target Security Group identifier (null for fleet-wide)
Display-friendly threshold expression
Number of events required to breach threshold
Evaluation lookback window for threshold breach detection
ANY_OCCURRENCE: No fixed period: a single matching event qualifies. The default of a rule; the engine looks back only a short period derived from its sweep interval, at least 10 secondsONE_MINUTE: Matching events are counted over a 60-second lookback; a threshold text such as 5 in 1 minute selects it when the stated minutes are below 5FIVE_MINUTES: Matching events are counted over a 300-second lookback; a threshold text selects it when the stated minutes are 5 or more
Formatted delivery description. A webhook destination in it is masked for the AUDITOR role, see recipient.
Outbound delivery channel type
Delivery destination (email address or webhook URL). The AUDITOR role receives a webhook destination masked to scheme and host (e.g. https://hooks.example.com/…); ADMIN and SECURITY_OPERATOR receive it in full.
Whether the rule is actively evaluated
Monotonically increasing semantic revision number
Rule provenance origin
SYSTEM: Built-in rule. It cannot be deleted or renamed and its trigger, threshold and scope cannot change; only the enabled flag and the delivery settings canCUSTOM: Rule created through the API by a user
Stable system identifier for built-in rules (null for custom rules)
Creation timestamp
Last update timestamp
400 Bad Request: VALIDATION_FAILED when the name is blank or too long, a text field is over its length limit or thresholdCount is below 1; INVALID_ALERT_RULE_NAME when the name is blank or longer than 255 characters after trimming; ALERT_RULE_CONDITION_REQUIRED when no trigger condition is given; ALERT_RULE_UNSUPPORTED_CONDITION when a condition or scope value is not supported or LICENSE_EXPIRY is used for a custom rule; ALERT_RULE_INVALID_THRESHOLD when the threshold count is not a number or is below 1; INVALID_DELIVERY_RECIPIENT when the recipient is not a valid email address or a public webhook URL; MALFORMED_REQUEST when the body cannot be read
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.
401 Unauthorized: UNAUTHENTICATED when the VTP_SESSION cookie is missing, unknown, expired or revoked
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.
403 Forbidden: FORBIDDEN when the signed-in role is not allowed to call this operation; CSRF_ERROR when the X-XSRF-TOKEN header is missing or wrong on a POST, PUT, PATCH or DELETE (only POST /api/v1/auth/login is exempt, and a request without a valid session gets 401 UNAUTHENTICATED instead); PASSWORD_CHANGE_REQUIRED when the account must change its password first (only GET /api/v1/auth/session, POST /api/v1/auth/logout and POST /api/v1/auth/change-password are exempt); LICENSE_REQUIRED or LICENSE_EXPIRED while the license pool is restricted (no license, or expired past grace) (exempt: every route under /api/v1/auth, GET /api/v1/user/preferences, GET /api/v1/licensing/summary and POST /api/v1/licensing/licenses)
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.
404 Not Found: GROUP_NOT_FOUND when groupScopeId or the scope name does not match a security group
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.
409 Conflict: ALERT_RULE_NAME_EXISTS when a rule with the name already exists; EXTERNAL_DELIVERY_DISABLED when an external delivery type (email or webhook) is requested, because external delivery is disabled
"ApiErrorResponse Object"
Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.
curl -X POST -H 'Authorization: <value>' -H 'Content-Type: application/json' -d '{"name":"string"}' https://{api_host}/api/v1/alert-rules