Create (This interface will be deprecated on 2025-12-30, v2 interface is recommended)¶

POST /api/v1/alert_policy/add

Overview¶

Create an alert policy

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: disabled), when enabled, the operation permissions for this rule are based on permissionSet Allow empty: False
permissionSet	array		Operation permission configuration, configurable (roles (except owner), member UUID, team UUID) Example: ['wsAdmin', 'acnt_xxxx', 'group_yyyy'] Allow empty: False
ruleTimezone	str	Y	Alert policy timezone Example: Asia/Shanghai Allow empty: False
alertOpt	json		Alert settings Allow empty: False
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		Repeat alert configuration Allow empty: False
alertOpt.silentTimeoutByStatusEnable	boolean		Whether to enable per-level repeat alert settings, default false, use silentTimeout configuration Allow empty: False
alertOpt.silentTimeoutByStatus	array		Per-level repeat alert settings, minimum alert interval configuration per level 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 for aggregation by label, only effective if df_label is specified in aggFields Allow empty: False
alertOpt.aggClusterFields	array		Field list for intelligent aggregation, only effective if CLUSTER is specified in aggFields, optional values "df_title": title, "df_message": content Example: ['df_title'] Allow empty: False

Parameter Supplementary Explanation¶

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 (parameter added in 2024-01-31 iteration)
alertOpt	Dict	Required	Alert settings
alertOpt.silentTimeout	integer		Minimum alert interval, how long to not resend the same alert (i.e., alert silence duration), in seconds/s, 0/null means send the alert only once (i.e., infinite interval)
alertOpt.silentTimeoutByStatusEnable	boolean		Whether to enable per-level repeat alert configuration
alertOpt.silentTimeoutByStatus	array		Minimum alert interval per level, in seconds, security inspection levels use `security_` prefix
alertOpt.aggInterval	integer		Alert aggregation interval, in seconds, 0 means no aggregation, unit 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 for aggregation by label, only effective if df_label is specified in aggFields
alertOpt.aggClusterFields	array		Field list for intelligent aggregation, only effective if CLUSTER is specified in aggFields, optional values "df_title": title, "df_message": content
alertOpt.alertTarget	Array[Dict]		Alert actions
alertOpt.alertType	string		Alert policy notification type, level(status)/member(member), default is level, added in 2024-11-06 iteration
openPermissionSet	boolean		Whether to enable custom permission configuration, default false, added in 2024-11-06 iteration
permissionSet	array		Operation permission configuration , added in 2024-11-06 iteration

2. When the alert policy is of type level, alertOpt.alertTarget Parameter Description

key	Type	Required	Description
alertTarget[#]	dict		alertTarget list element
alertTarget[#].name	string		Configuration name
alertTarget[#].targets	Array[dict]	Required	Notification target configuration (note the position of this field when the alert policy is of type level/member)
alertTarget[#].crontab	String		When selecting a repeating time period, start Crontab (Crontab syntax)
alertTarget[#].crontabDuration	integer		When selecting a repeating time, duration from Crontab start (seconds)
alertTarget[#].customDateUUIDs	Array[String]		When selecting a custom time, UUID list of custom notification dates, e.g.: ['ndate_xxxx32', 'ndate_xxxx32'], refer to (Monitoring - Alert Policy - Custom Notification Date, interface) for custom notification dates
alertTarget[#].customStartTime	String		When selecting a custom time, daily start time, format: HHss
alertTarget[#].customDuration	integer		When selecting a custom time period, duration from customStartTime custom start time (seconds)

3. When the alert policy is of type member, alertOpt.alertTarget Parameter Description

key	Type	Required	Description
alertTarget[#]	dict		alertTarget list element
alertTarget[#].name	string		Configuration name
alertTarget[#].crontab	String		When selecting a repeating time period, start Crontab (Crontab syntax)
alertTarget[#].crontabDuration	integer		When selecting a repeating time, duration from Crontab start (seconds)
alertTarget[#].customDateUUIDs	Array[String]		When selecting a custom time, UUID list of custom notification dates, e.g.: ['ndate_xxxx32', 'ndate_xxxx32'], refer to (Monitoring - Alert Policy - Custom Notification Date, interface) for custom notification dates
alertTarget[#].customStartTime	String		When selecting a custom time, daily start time, format: HHss
alertTarget[#].customDuration	integer		When selecting a custom time period, duration from customStartTime custom start time (seconds)
alertTarget[#].alertInfo	Array[dict]	Required	When the alert policy is of type member, notification related information configuration added in 2024-11-27 iteration

4. When the alert policy is of type member, alertOpt.alertTarget.alertInfo Parameter Description

key	Type	Required	Description
alertInfo[#]	string		alertInfo list element
alertInfo[#].name	string		Configuration name
alertInfo[#].targets	Array[dict]	Required	Notification target configuration (note the position of this field when the alert policy is of type level/member)
alertInfo[#].filterString	string		When alertType is member, use this field, filter condition original string, added in 2024-11-27 iteration
alertInfo[#].memberInfo	array		When alertType is member, use this field (team UUID, member UUID), e.g.: [`group_xxxx`,`acnt_xxxx`], added in 2024-11-27 iteration

5. Time Configuration Related Explanation

If selecting a repeating time period, crontab, crontabDuration fields are required parameters.
If selecting a custom time period, customDateUUIDs, customDuration, customStartTime fields are required parameters.
If selecting other times, crontab, crontabDuration, customDateUUIDs, customStartTime, customDuration do not need to be passed.
Note: Each alert policy will have a notification rule for other times, i.e., the fallback notification target without time configuration.

6. Notification Target Field targets Explanation

When alertType is status, targets location is alertOpt.alertTarget.targets
When alertType is member, targets location is 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 target/member/team, example: [`group_xxxx`,`acnt_xxxx`,`notify_xxxx`]. (When alertType is member, only notification targets and fixed fields email, sms (saas version supports sms) can be selected, example: [`email`,`notify_xxxx`], added in 2024-11-06 iteration)
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 inspection type status values: `fatal`, `critical`,`error`,`warning`,`nodata`,`info`. Security inspection type status values: `critical`, `high`, `medium`, `low`, `info` (security inspection enum values added in 2025-05-14 iteration)
df_source	Enum		When status needs to be a security inspection status, df_source must be specified as security here, default not passed means non-security inspection status (added in 2025-05-14 iteration)
upgradeTargets	Array		Escalation notification for each alert configuration status
tags	dict		Filter conditions
filterString	dict		Filter condition original string can replace tags, filterString usage priority is greater than tags, added in 2024-11-27 iteration

7. Notification Target Field upgradeTargets Explanation

When alertType is status, targets location is alertOpt.alertTarget.targets.upgradeTargets
When alertType is member, targets location is alertOpt.alertTarget.alertInfo.targets.upgradeTargets
upgradeTargets is a list, internal elements are dict, internal field description as follows

key	Type	Required	Description
to	Array[String]	Required	Notification target/member/team, example: [`group_xxxx`,`acnt_xxxx`,`notify_xxxx`]. (When alertType is member, only members and teams can be selected, added in 2024-11-06 iteration)
duration	integer		Duration, continuously generating events of this level status triggers escalation notification
toWay	Array[String]		When alertType is member type, use, only notification targets and fixed fields email, sms (saas version supports sms) can be selected, example: [`email`,`notify_xxxx`], added in 2024-11-06 iteration

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

**permissionSet, openPermissionSet Field Description (fields added in 2024-06-26 iteration): **

After configuring openPermissionSet to be enabled, only the workspace owner and roles, teams, members belonging to the permissionSet configuration can edit/enable/disable/delete.
After configuring openPermissionSet to be disabled (default), then delete/enable/disable/edit permissions follow the original interface edit/enable/disable/delete permissions.

permissionSet field can be configured, role UUID (wsAdmin,general, readOnly, role_xxxxx ), team UUID (group_yyyy), member UUID (acnt_xxx) permissionSet field example:

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

9. alertOpt[#].silentTimeoutByStatus Parameter Description

Parameter Name	type	Description
silentTimeoutByStatus[#]	dict	silentTimeoutByStatus list element
silentTimeoutByStatus[#].status	boolean	Non-security inspection type status values: `fatal`, `critical`,`error`,`warning`,`nodata`,`info`. Security inspection type status values: `security_critical`, `security_high`, `security_medium`, `security_low`, `security_info`
silentTimeoutByStatus[#].silentTimeout	integer	Minimum alert interval, how long to not resend the same alert (i.e., alert silence duration), in seconds/s, 0/null means send the alert only once (i.e., infinite interval)

silentTimeoutByStatus field example:

  [
      {
          "status": "fatal",
          "silentTimeout": 600
      },
      {
          "status": "critical,error",
          "silentTimeout": 900
      },
      {
          "status": "security_high",
          "silentTimeout": 600
      },
  ]

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