Skip to content

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🇲🇲ss
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🇲🇲ss
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:

  ["wsAdmin", "general", "group_yyyy", "acnt_xxxx"]    


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"
}

Feedback

Is this page helpful? ×