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 null: False
desc	string		Description Allow null: 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 null: False
permissionSet	array		Operation permission configuration, configurable (roles (except owner), member UUIDs, team UUIDs) Example: ['wsAdmin', 'acnt_xxxx', 'group_yyyy'] Allow null: False
ruleTimezone	str	Y	Alert policy timezone Example: Asia/Shanghai Allow null: False
alertOpt	json		Alert settings Allow null: False
alertOpt.alertType	string		Alert policy notification type, level(status)/member(member), default is level Allow null: False Allowed 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 null: False
alertOpt.silentTimeout	integer		Repeat alert configuration Allow null: False
alertOpt.silentTimeoutByStatusEnable	boolean		Whether to enable per-level repeat alert settings, default false, uses silentTimeout configuration Allow null: False
alertOpt.silentTimeoutByStatus	array		Per-level repeat alert settings, minimum alert interval configuration per level Allow null: False
alertOpt.aggInterval	integer	Y	Alert aggregation interval, in seconds, 0 means no aggregation Allow null: False $minValue: 0 $maxValue: 1800
alertOpt.aggFields	array		Aggregation field list, keep empty list [] to indicate "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 null: False
alertOpt.aggLabels	array		Label value list for aggregation by label, only takes effect if df_label is specified in aggFields Allow null: False
alertOpt.aggClusterFields	array		Field list for intelligent aggregation, only takes effect if CLUSTER is specified in aggFields, allowed values "df_title": title, "df_message": content Example: ['df_title'] Allow null: False

Parameter Supplementary Description¶

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 before the same alert is not sent again (i.e., alert mute duration), unit seconds/s, 0/null means send 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, unit seconds, security inspection levels use `security_` prefix
alertOpt.aggInterval	integer		Alert aggregation interval, unit seconds, 0 means no aggregation, unit seconds/s range [0,1800]
alertOpt.aggFields	array		Aggregation field list, keep empty list [] to indicate "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 takes effect if df_label is specified in aggFields
alertOpt.aggClusterFields	array		Field list for intelligent aggregation, only takes effect if CLUSTER is specified in aggFields, allowed 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. Parameter Description for alertOpt.alertTarget when Alert Policy is Level Type

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 for level/member type alert policies)
alertTarget[#].crontab	String		Start Crontab when selecting repeated time periods (Crontab syntax)
alertTarget[#].crontabDuration	integer		Duration (seconds) from Crontab start when selecting repeated time
alertTarget[#].customDateUUIDs	Array[String]		UUID list of custom notification dates when selecting custom time, e.g., ['ndate_xxxx32', 'ndate_xxxx32'], refer to (Monitoring - Alert Policies - Custom Notification Dates, interface)
alertTarget[#].customStartTime	String		Daily start time when selecting custom time, format: HHss
alertTarget[#].customDuration	integer		Duration (seconds) from customStartTime when selecting custom time period

3. Parameter Description for alertOpt.alertTarget when Alert Policy is Member Type

key	Type	Required	Description
alertTarget[#]	dict		alertTarget list element
alertTarget[#].name	string		Configuration name
alertTarget[#].crontab	String		Start Crontab when selecting repeated time periods (Crontab syntax)
alertTarget[#].crontabDuration	integer		Duration (seconds) from Crontab start when selecting repeated time
alertTarget[#].customDateUUIDs	Array[String]		UUID list of custom notification dates when selecting custom time, e.g., ['ndate_xxxx32', 'ndate_xxxx32'], refer to (Monitoring - Alert Policies - Custom Notification Dates, interface)
alertTarget[#].customStartTime	String		Daily start time when selecting custom time, format: HHss
alertTarget[#].customDuration	integer		Duration (seconds) from customStartTime when selecting custom time period
alertTarget[#].alertInfo	Array[dict]	Required	Notification related information configuration for member-type alert policies, added in 2024-11-27 iteration

4. Parameter Description for alertOpt.alertTarget.alertInfo when Alert Policy is Member Type

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

5. Time Configuration Related Description

If selecting repeated time period, crontab, crontabDuration fields are required parameters
If selecting custom time period, 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., the fallback notification target without time configuration

6. Notification Target Field targets Description

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 trigger the alert (multiple statuses can be separated by commas, All means all). Non-security inspection status values: `fatal`, `critical`,`error`,`warning`,`nodata`,`info`. Security inspection 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		Upgrade notification for each alert configuration status
tags	dict		Filter conditions
filterString	dict		Raw filter condition string can replace tags, filterString has higher priority than tags, added in 2024-11-27 iteration

7. Notification Target Field upgradeTargets Description

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, triggers upgrade notification when events of this status level persist
toWay	Array[String]		Used when alertType is member(member) type, 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 enabled, only workspace owners and roles, teams, members belonging to the permissionSet configuration can edit/enable/disable/delete
After configuring openPermissionSet to disabled (default), then delete/enable/disable/edit permissions follow the original interface edit/enable/disable/delete permissions

permissionSet field can be configured with, role UUIDs (wsAdmin,general, readOnly, role_xxxxx ), team UUIDs (group_yyyy), member UUIDs (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 status values: `fatal`, `critical`,`error`,`warning`,`nodata`,`info`. Security inspection status values: `security_critical`, `security_high`, `security_medium`, `security_low`, `security_info`
silentTimeoutByStatus[#].silentTimeout	integer	Minimum alert interval, how long before the same alert is not sent again (i.e., alert mute duration), unit seconds/s, 0/null means send 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.truewatch.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"
}