Update a rule
To update a rule, you must have all
privileges for the appropriate Kibana features, depending on the consumer
and rule_type_id
of the rule you're updating. For example, you must have privileges for the Management > Stack rules feature, Analytics > Discover and Machine Learning features, Observability features, or Security features. If the rule has actions, you must also have read
privileges for the Management > Actions and Connectors feature. This API supports both key- and token-based authentication. To use key-based authentication, create an API key in Kibana and use it in the header of the API call. To use token-based authentication, provide a username and password; an API key that matches the current privileges of the user is created automatically. In both cases, the API key is subsequently used for authorization when the rule runs. NOTE: If the API key has different privileges than the key that created or most recently updated the rule, the rule behavior might change. Though some properties are optional, when you update the rule the existing property values are overwritten with default values. Therefore, it is recommended to explicitly set all property values.
Path parameters
-
An identifier for the rule.
Body Required
The update rule API request body varies depending on the type of rule and actions.
-
actions array[object] | null
Default value is
[]
(empty). -
alert_delay object
Indicates that an alert occurs only when the specified number of consecutive runs met the rule conditions.
-
The name of the rule.
-
Deprecated in 8.13.0. Use the
notify_when
property in the actionfrequency
object instead. Indicates how often alerts generate actions. NOTE: You cannot specifynotify_when
at both the rule and action level. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.Values are
onActionGroupChange
,onActiveAlert
, oronThrottleInterval
. -
The parameters for the rule.
-
The check interval, which specifies how frequently the rule conditions are checked. The interval is specified in seconds, minutes, hours, or days.
-
Deprecated in 8.13.0. Use the
throttle
property in the actionfrequency
object instead. The throttle interval, which defines how often an alert generates repeated actions. NOTE: You cannot specify the throttle interval at both the rule and action level. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
curl \
-X PUT https://localhost:5601/api/alerting/rule/ac4e6b90-6be7-11eb-ba0d-9b1c1f912d74 \
-H "Content-Type: application/json; Elastic-Api-Version=2023-10-31" \
-H "kbn-xsrf: string"
{
"name": "new name",
"tags": [],
"params": {
"index": [
".updated-index"
],
"aggType": "avg",
"groupBy": "top",
"aggField": "sheet.version",
"termSize": 6,
"termField": "name.keyword",
"threshold": [
1000
],
"timeField": "@timestamp",
"timeWindowSize": 5,
"timeWindowUnit": "m",
"thresholdComparator": ">"
},
"actions": [
{
"id": "96b668d0-a1b6-11ed-afdf-d39a49596974",
"group": "threshold met",
"params": {
"level": "info",
"message": "Rule {{rule.name}} is active for group {{context.group}}:\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}}\n- Timestamp: {{context.date}}"
},
"frequency": {
"summary": false,
"notify_when": "onActionGroupChange"
}
}
],
"schedule": {
"interval": "1m"
}
}
{
"id": "ac4e6b90-6be7-11eb-ba0d-9b1c1f912d74",
"name": "new name",
"tags": [],
"params": {
"index": [
".updated-index"
],
"aggType": "avg",
"groupBy": "top",
"aggField": "sheet.version",
"termSize": 6,
"termField": "name.keyword",
"threshold": [
1000
],
"timeField": "@timestamp",
"timeWindowSize": 5,
"timeWindowUnit": "m",
"thresholdComparator": ">"
},
"actions": [
{
"id": "96b668d0-a1b6-11ed-afdf-d39a49596974",
"uuid": "07aef2a0-9eed-4ef9-94ec-39ba58eb609d",
"group": "threshold met",
"params": {
"level": "info",
"message": "Rule {{rule.name}} is active for group {{context.group}}:\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}}\n- Timestamp: {{context.date}"
},
"frequency": {
"summary": false,
"throttle": null,
"notify_when": "onActionGroupChange"
},
"connector_type_id": ".server-log"
}
],
"enabled": true,
"running": false,
"consumer": "alerts",
"last_run": {
"outcome": "succeeded",
"warning": null,
"outcome_msg": null,
"alerts_count": {
"new": 0,
"active": 0,
"ignored": 0,
"recovered": 0
}
},
"mute_all": false,
"next_run": "2024-03-26T23:23:51.316Z",
"revision": 1,
"schedule": {
"interval": "1m"
},
"throttle": null,
"created_at": "2024-03-26T23:13:20.985Z",
"created_by": "elastic",
"updated_at": "2024-03-26T23:22:59.949Z",
"updated_by": "elastic",
"rule_type_id": ".index-threshold",
"api_key_owner": "elastic",
"muted_alert_ids": [],
"execution_status": {
"status": "ok",
"last_duration": 52,
"last_execution_date": "2024-03-26T23:22:51.390Z"
},
"scheduled_task_id": "4c5eda00-e74f-11ec-b72f-5b18752ff9ea",
"api_key_created_by_user": false
}
{
"error": "Unauthorized",
"message": "string",
"statusCode": 401
}
{
"error": "Not Found",
"message": "Saved object [alert/caaad6d0-920c-11ed-b36a-874bd1548a00] not found",
"statusCode": 404
}