Alert Rules Operations Create

Alert Rules Operations Create
Create a new Alert Rule

Create a new Alert Rule and its delivery destination. Requires ADMIN or SECURITY_OPERATOR.

Request
URI
POST
https://{api_host}/api/v1/alert-rules
COPY
Request Body

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.

CreateAlertRuleRequest of type(s) application/json
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
}
string
name
Required  

Name of the new Alert Rule. Required; stored trimmed, at most 255 characters, and no other Alert Rule may have the same name

string
trigger
Optional

Display trigger string or canonical condition label

string
triggerType
Optional

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
Enumeration: OUTCOME, EVENT_CLASS, EVENT_CATEGORY, LICENSE_EXPIRY
string
triggerValue
Optional

Canonical trigger literal

string
scope
Optional

Target scope string (e.g. All Hypervisors, All Groups)

integer As int64 As int64
groupScopeId
Optional

Target Security Group ID (optional, null for fleet-wide)

string
threshold
Optional

Threshold expression (e.g. 'Any occurrence' or '5 in 1 minute')

integer As int32 As int32
thresholdCount
Optional

Threshold count (>= 1)

string
thresholdWindow
Optional

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 seconds
  • ONE_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 5
  • FIVE_MINUTES: Matching events are counted over a 300-second lookback; a threshold text selects it when the stated minutes are 5 or more
Enumeration: ANY_OCCURRENCE, ONE_MINUTE, FIVE_MINUTES
string
delivery
Optional

Formatted delivery string (e.g. 'Email · [email protected]')

string
deliveryType
Optional

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 given
  • WEBHOOK: 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
Enumeration: EMAIL, WEBHOOK
string
recipient
Optional

Delivery destination (email address or webhook URL)

boolean
enabled
Optional

Whether the rule is enabled initially

Authentication
This operation uses the following authentication methods.
Responses
201

201 Created successful response envelope. The created alert rule with its delivery destination

Returns AlertRuleDto of type(s) application/json
{
    "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
id
Required  

String identifier matching frontend requirements

integer As int64 As int64
alertRuleId
Required  

Unique canonical Alert Rule identifier

string
name
Required  

Human-readable rule name

string
trigger
Required  

Display-friendly trigger label (e.g. Outcome = Enforced (blocked))

string
triggerType
Required  

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
Enumeration: OUTCOME, EVENT_CLASS, EVENT_CATEGORY, LICENSE_EXPIRY
string
triggerValue
Required  

Canonical trigger value matching schema enums

string
scope
Required  

Display scope label (e.g. All Hypervisors or group name)

integer As int64 As int64
groupScopeId
Optional

Target Security Group identifier (null for fleet-wide)

string
threshold
Required  

Display-friendly threshold expression

integer As int32 As int32
thresholdCount
Required  

Number of events required to breach threshold

string
thresholdWindow
Required  

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 seconds
  • ONE_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 5
  • FIVE_MINUTES: Matching events are counted over a 300-second lookback; a threshold text selects it when the stated minutes are 5 or more
Enumeration: ANY_OCCURRENCE, ONE_MINUTE, FIVE_MINUTES
string
delivery
Optional

Formatted delivery description. A webhook destination in it is masked for the AUDITOR role, see recipient.

deliveryType
Optional

Outbound delivery channel type

string
recipient
Optional

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.

boolean
enabled
Required  

Whether the rule is actively evaluated

integer As int32 As int32
revision
Required  

Monotonically increasing semantic revision number

string
ruleSource
Required  

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 can
  • CUSTOM: Rule created through the API by a user
Enumeration: SYSTEM, CUSTOM
string
systemKey
Optional

Stable system identifier for built-in rules (null for custom rules)

string As date-time As date-time
createdAt
Required  

Creation timestamp

string As date-time As date-time
updatedAt
Required  

Last update timestamp


400

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

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

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.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

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

401 Unauthorized: UNAUTHENTICATED when the VTP_SESSION cookie is missing, unknown, expired or revoked

Returns Unauthenticated of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

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.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

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

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)

Returns ForbiddenWrite of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

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.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

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

404 Not Found: GROUP_NOT_FOUND when groupScopeId or the scope name does not match a security group

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

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.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

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

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

Returns ApiErrorResponse of type(s) application/json
"ApiErrorResponse Object"
errorCode
Required  

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.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


Code Samples
COPY
                    curl -X POST -H 'Authorization: <value>' -H 'Content-Type: application/json' -d '{"name":"string"}' https://{api_host}/api/v1/alert-rules