Create v2¶
POST /api/v1/alert_policy/add_v2
Overview¶
Create an alert policy, v2 supports synchronous updates to associated monitors/intelligent monitors/intelligent inspections/SLOs, security monitoring.
Body Request Parameters¶
Parameter Name | Type | Required | Description |
---|---|---|---|
name | string | Y | Alert policy name Allow empty: False |
desc | string | Description Allow empty: False Allow empty string: True Max length: 256 |
|
openPermissionSet | boolean | Enable custom permission configuration, (default false: not enabled), when enabled, the operation permissions of this rule are based on permissionSet Allow empty: False |
|
permissionSet | array | Operation permission configuration, configurable (roles (except owner), member UUIDs, team UUIDs) Example: ['wsAdmin', 'acnt_xxxx', 'group_yyyy'] Allow empty: False |
|
checkerUUIDs | array | Monitor/intelligent monitor/intelligent inspection/SLO UUIDs (2024-12-11 iteration added) Example: ['rule_xxx', 'monitor_xxx'] Allow empty: False |
|
securityRuleUUIDs | array | Security monitoring (CSPM, SIEM) UUIDs Example: ['srul_xxx', 'srul_xxx', 'srul_xxx'] Allow empty: False |
|
ruleTimezone | str | Y | Alert policy timezone Example: Asia/Shanghai Allow empty: False |
alertOpt | json | Alert settings Allow empty: False |
|
alertOpt.aggType | string | Alert aggregation type, not passing this field defaults to old version logic 2024-12-25 iteration added Allow empty: True Optional values: ['byFields', 'byCluster', 'byAI'] |
|
alertOpt.alertType | string | Alert policy notification type, level(status)/member(member), default is level Allow empty: False Optional values: ['status', 'member'] |
|
alertOpt.alertTarget | array | Trigger actions, note the parameter handling for trigger times Example: [{'name': 'Notification Configuration1', 'targets': [{'to': ['acnt_xxxx32'], 'status': 'critical', 'tags': {'pod_name': ['coredns-7769b554cf-w95fk']}, 'upgradeTargets': [{'to': ['acnt_xxxx32'], 'duration': 600}, {'to': ['group_xxxx32'], 'duration': 6000}]}], 'crontabDuration': 600, 'crontab': '0 9 * * 0,1,2,3,4'}, {'name': 'Notification Configuration2', 'targets': [{'status': 'error', 'to': ['group_xxxx32'], 'upgradeTargets': [{'to': ['acnt_xxxx32'], 'duration': 600}, {'to': ['group_xxxx32'], 'duration': 6000}]}], 'customDateUUIDs': ['ndate_xxxx32'], 'customStartTime': '09:30:10', 'crontabDuration': 600}] Allow empty: False |
|
alertOpt.silentTimeout | integer | Y | Alert settings Allow empty: False |
alertOpt.aggInterval | integer | Y | Alert aggregation interval, in seconds, 0 means no aggregation Allow empty: False $minValue: 0 $maxValue: 1800 |
alertOpt.aggFields | array | Aggregation field list, keep empty list [] to mean "aggregation rule: all", df_monitor_checker_id: monitor/intelligent inspection/SLO, df_dimension_tags: detection dimension, df_label: label, CLUSTER: intelligent aggregation Example: ['CLUSTER'] Allow empty: False |
|
alertOpt.aggLabels | array | Label value list when aggregating by label, will only take effect if df_label is specified in aggFields Allow empty: False |
|
alertOpt.aggClusterFields | array | Field list for intelligent aggregation, will only take effect if CLUSTER is specified in aggFields, optional values "df_title": title, "df_message": content Example: ['df_title'] Allow empty: False |
|
alertOpt.aggSendFirst | boolean | Whether to send the first alert directly during aggregation (2025-09-03 iteration added parameter) Allow empty: False |
Parameter Additional Notes¶
Data Description.
1. alertOpt Parameter Description
Parameter Name | Type | Required | Description |
---|---|---|---|
name | string | Required | Rule name |
desc | string | Description | |
type | string | Required | Checker type |
ruleTimezone | string | Required | Alert policy timezone (2024-01-31 iteration added parameter) |
alertOpt | Dict | Required | Alert settings |
alertOpt[#].silentTimeout | integer | Required | How long the same alert will not be sent again (i.e., silence time), in seconds/s, 0 means permanent |
alertOpt[#].aggInterval | integer | Alert aggregation interval, in seconds, 0 means no aggregation, in seconds/s range [0,1800] | |
alertOpt[#].aggFields | array | Aggregation field list, keep empty list [] to mean "aggregation rule: all", df_monitor_checker_id: monitor/intelligent inspection/SLO, df_dimension_tags: detection dimension, df_label: label, CLUSTER: intelligent aggregation | |
alertOpt[#].aggLabels | array | Label value list when aggregating by label, will only take effect if df_label is specified in aggFields | |
alertOpt[#].aggClusterFields | array | Field list for intelligent aggregation, will only take effect if CLUSTER is specified in aggFields, optional values "df_title": title, "df_message": content | |
alertOpt[#].aggSendFirst | boolean | Whether to send the first alert directly during aggregation (2025-09-03 iteration added parameter) | |
alertOpt[#].alertTarget | Array[Dict] | Alert actions | |
alertOpt[#].alertType | string | Alert policy notification type, level(status)/member(member), default is level, 2024-11-06 iteration added | |
alertOpt[#].aggType | string | Default not passing follows old version logic, byFields: rule aggregation, byCluster: intelligent aggregation, byAI: AI aggregation, 2024-12-25 added field | |
openPermissionSet | boolean | Whether to enable custom permission configuration, default false, 2024-11-06 iteration added | |
permissionSet | array | Operation permission configuration, 2024-11-06 iteration added | |
checkerUUIDs | array | Associated monitor/intelligent monitor/intelligent inspection/SLO UUIDs, 2024-12-11 iteration added | |
securityRuleUUIDs | array | Associated security monitoring (CSPM, SIEM) UUIDs, 2025-05-14 iteration added |
1.1 alertOpt.aggType Parameter Description
2024-12-25
Alert aggregation type:
null: no aggregation
byFields: rule aggregation
byCluster: intelligent aggregation
byAI: AI aggregation
In the old data structure, since the aggType field does not exist, the aggregation type is determined by the content of aggFields. Therefore, after adding the aggType field, it will be compatible as follows:
When aggType is specified, aggregate according to the specified aggregation method
When aggType is not specified or aggType=None (follows old version logic)
If aggFields contains "CLUSTER", aggregate according to intelligent aggregation
If aggFields does not contain "CLUSTER", aggregate according to rule aggregation
Derived rules:
Specifying aggInterval=0 or aggInterval=null still means "no aggregation"
When aggType="byCluster", "CLUSTER" can be omitted in aggFields (whether passed or not does not affect)
When aggType="byFields", but aggFields contains "CLUSTER", "CLUSTER" will be ignored (i.e., aggType has higher priority)
2. When the alert policy is of type level alertOpt.alertTarget
Parameter Description
key | Type | Required | Description |
---|---|---|---|
name | string | Configuration name | |
targets | Array[dict] | Required | Notification object configuration (note the position of this field when the alert policy is of type level/member) |
crontab | String | When selecting repeated time periods, start Crontab (Crontab syntax) | |
crontabDuration | integer | When selecting repeated time periods, duration from Crontab start (seconds) | |
customDateUUIDs | Array[String] | When selecting custom time periods, custom notification date UUID list, example: ['ndate_xxxx32', 'ndate_xxxx32'], custom notification date reference (monitoring - alert policy - custom notification date, interface) | |
customStartTime | String | When selecting custom time periods, daily start time, format: HH |
|
customDuration | integer | When selecting custom time periods, duration from customStartTime custom start time (seconds) |
3. When the alert policy is of type member alertOpt.alertTarget
Parameter Description
key | Type | Required | Description |
---|---|---|---|
name | string | Configuration name | |
crontab | String | When selecting repeated time periods, start Crontab (Crontab syntax) | |
crontabDuration | integer | When selecting repeated time periods, duration from Crontab start (seconds) | |
customDateUUIDs | Array[String] | When selecting custom time periods, custom notification date UUID list, example: ['ndate_xxxx32', 'ndate_xxxx32'], custom notification date reference (monitoring - alert policy - custom notification date, interface) | |
customStartTime | String | When selecting custom time periods, daily start time, format: HH |
|
customDuration | integer | When selecting custom time periods, duration from customStartTime custom start time (seconds) | |
alertInfo | Array[dict] | Required | When the alert policy is of type member, notification related information configuration 2024-11-27 iteration added |
4. When the alert policy is of type member alertOpt.alertTarget.alertInfo
Parameter Description
key | Type | Required | Description |
---|---|---|---|
name | string | Configuration name | |
targets | Array[dict] | Required | Notification object configuration (note the position of this field when the alert policy is of type level/member) |
filterString | string | When alertType is member, use this field, filter condition original string, 2024-11-27 iteration added | |
memberInfo | array | When alertType is member, use this field (team UUID member UUID), example: [group_xxxx ,acnt_xxxx ], 2024-11-27 iteration added |
5. Time Configuration Related Notes
If selecting repeated time periods, crontab, crontabDuration fields are required parameters
If selecting custom time periods, customDateUUIDs, customDuration, customStartTime fields are required parameters
If selecting other times, crontab, crontabDuration, customDateUUIDs, customStartTime, customDuration are not required
Note: Each alert policy will have a notification rule for other times, i.e., no time configuration as a fallback notification object
6. Notification Object Field targets
Description
When alertType is status, targets position alertOpt.alertTarget.targets
When alertType is member, targets position alertOpt.alertTarget.alertInfo.targets
targets is a list, internal elements are dict, internal field description as follows:
key | Type | Required | Description |
---|---|---|---|
to | Array[String] | Required | Notification object/member/team, example: [group_xxxx ,acnt_xxxx ,notify_xxxx ]. (When alertType is member, only notification objects and fixed fields email, sms (SaaS version supports sms) can be selected, example: [email ,notify_xxxx ], 2024-11-06 iteration added) |
status | Enum | Required | The status value of the event that needs to send an alert (multiple statuses can be separated by commas, all means all). Non-security monitoring type status values: critical ,error ,warning ,nodata ,info . Security monitoring type status values: critical , high , medium , low , info (2025-05-14 iteration added security monitoring enum values) |
df_source | Enum | When status needs to be security monitoring status, df_source must be specified as security, default not passed means non-security monitoring status (2025-05-14 iteration added) | |
upgradeTargets | Array | Upgrade notification for each alert configuration status | |
tags | dict | Filter conditions | |
filterString | dict | Filter condition original string can replace tags, filterString has higher priority than tags, 2024-11-27 iteration added |
7. Notification Object Field upgradeTargets
Description
<br/>
When alertType is status, targets position alertOpt.alertTarget.targets.upgradeTargets
When alertType is member, targets position alertOpt.alertTarget.alertInfo.targets.upgradeTargets
7.1 upgradeTargets is a list, internal elements are dict, internal field description as follows:
key | Type | Required | Description |
---|---|---|---|
to | Array[String] | Required | Notification object/member/team, example: [group_xxxx ,acnt_xxxx ,notify_xxxx ]. (When alertType is member, only members and teams can be selected, 2024-11-06 iteration added) |
duration | integer | Duration, continuous generation of events of this level status triggers upgrade notification | |
toWay | Array[String] | When alertType is member type, use, only notification objects and fixed fields email, sms (SaaS version supports sms) can be selected, example: [email ,notify_xxxx ], 2024-11-06 iteration added |
8. Operation Permission Configuration Parameter Description
Parameter Name | Type | Description |
---|---|---|
openPermissionSet | boolean | Whether to enable custom permission configuration, default false |
permissionSet | array | Operation permission configuration |
8.1permissionSet, openPermissionSet Field Description (2024-06-26 iteration added fields):
When openPermissionSet is enabled, only the workspace owner and roles, teams, members in the permissionSet configuration can edit/enable/disable/delete
When openPermissionSet is disabled (default), then delete/enable/disable/edit permissions follow the original interface edit/enable/disable/delete permissions
permissionSet field can be configured, role UUIDs (wsAdmin,general, readOnly, role_xxxxx ), team UUIDs (group_yyyy), member UUIDs (acnt_xxx)
permissionSet field example:
Request Example¶
curl 'https://openapi.guance.com/api/v1/alert_policy/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-raw '{"name":"jj_test","ruleTimezone":"Asia/Shanghai","alertOpt":{"alertTarget":[{"name":"Notification Configuration1","targets":[{"status":"critical","tags":{"pod_name":["coredns-7769b554cf-w95fk"]},"to":["acnt_xxxx32"]}],"crontabDuration":600,"crontab":"0 9 * * 0,1,2,3,4"},{"name":"Notification Configuration2","targets":[{"status":"error","to":["group_xxxx32"]}],"customDateUUIDs":["ndate_xxxx32"],"customStartTime":"09:30:10","customDuration":600},{"targets":[{"status":"warning","to":["notify_xxxx32"]}]}],"silentTimeout":21600,"aggInterval":120,"aggFields":["df_monitor_checker_id"]}}' \
--compressed
Response¶
{
"code": 200,
"content": {
"alertOpt": {
"aggFields": [
"df_monitor_checker_id"
],
"aggInterval": 120,
"alertTarget": [
{
"crontab": "0 9 * * 0,1,2,3,4",
"crontabDuration": 600,
"name": "Notification Configuration1",
"targets": [
{
"status": "critical",
"tags": {
"pod_name": [
"coredns-7769b554cf-w95fk"
]
},
"to": [
"acnt_xxxx32"
]
}
]
},
{
"customDateUUIDs": [
"ndate_xxxx32"
],
"customDuration": 600,
"customStartTime": "09:30:10",
"name": "Notification Configuration2",
"targets": [
{
"status": "error",
"to": [
"group_xxxx32"
]
}
]
},
{
"targets": [
{
"status": "warning",
"to": [
"notify_xxxx32"
]
}
]
}
],
"silentTimeout": 21600
},
"createAt": 1719373984,
"creator": "wsak_xxxx32",
"declaration": {
"asd": "aa,bb,cc,1,True",
"asdasd": "dawdawd",
"business": "aaa",
"fawf": "afawf",
"organization": "64fe7b4062f74d0007b46676"
},
"deleteAt": -1,
"id": null,
"name": "jj_test",
"ruleTimezone": "Asia/Shanghai",
"score": 0,
"status": 0,
"updateAt": 1719373984,
"updator": "wsak_xxxx32",
"uuid": "altpl_xxxx32",
"workspaceUUID": "wksp_xxxx32"
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-148B6846-6180-4594-BD26-8A2077F0E911"
}