Update rule API
editUpdate rule API
editUpdate the attributes for an existing rule.
For the most up-to-date API details, refer to the open API specification.
Request
editPUT <kibana host>:<port>/api/alerting/rule/<id>
PUT <kibana host>:<port>/s/<space_id>/api/alerting/rule/<id>
Prerequisites
editYou 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, the
Management > Stack Rules feature, Analytics > Discover and Machine Learning
features, Observability, or Security features. If the rule has
actions
, you must also have read
privileges for the Management >
Actions and Connectors feature. For more details, refer to
Feature privileges.
Path parameters
edit-
id
- (Required, string) The ID of the rule that you want to update.
-
space_id
-
(Optional, string) An identifier for the space. If
space_id
is not provided in the URL, the default space is used.
Request body
edit-
actions
-
(Optional, object array) An array of action objects. The default value is an empty array (
[]
).Properties of the action objects:
-
group
-
(Required, string) Grouping actions is recommended for escalations for different
types of alerts. If you don’t need this, set the value to
default
. -
id
- (Required, string) The identifier of the action.
-
params
-
(Required, object) The map to the
params
that the connector type will receive. Theparams
are handled as Mustache templates and passed a default set of context.
-
-
name
- (Required, string) A name to reference and search.
-
notify_when
-
(Required, string) The condition for throttling the notification:
onActionGroupChange
,onActiveAlert
, oronThrottleInterval
. -
params
-
(Required, object) The parameters to pass to the rule type executor
params
value. This will also validate against the rule type params validator, if defined. -
schedule
-
(Required, object) When to run this rule. Use one of the available schedule formats.
Schedule formats
A schedule uses a
key: value
format. Kibana currently supports the interval format, which specifies the interval in seconds, minutes, hours, or days at which to run the rule. For example:{ "interval": "10s" }
,{ "interval": "5m" }
,{ "interval": "1h" }
, or{ "interval": "1d" }
. -
tags
-
(Optional, string array) A list of keywords to reference and search. The default
value is an empty array (
[]
). -
throttle
-
(Optional, string) How often this rule should fire the same actions. This will
prevent the rule from sending out the same notification over and over. For
example, if a rule with a
schedule
of 1 minute stays in a triggered state for 90 minutes, setting athrottle
of10m
or1h
will prevent it from sending 90 notifications during this period. The default value isnull
.
Response codes
edit-
200
- Indicates a successful call.
Examples
editUpdate an index threshold rule with ID ac4e6b90-6be7-11eb-ba0d-9b1c1f912d74
:
PUT api/alerting/rule/ac4e6b90-6be7-11eb-ba0d-9b1c1f912d74 { "notify_when": "onActionGroupChange", "params": { "index":[".test-index"], "timeField":"@timestamp", "groupBy":"top", "aggType":"avg", "timeWindowSize":5, "timeWindowUnit":"m", "thresholdComparator":">", "threshold":[1000], "aggField":"sheet.version", "termField":"name.keyword", "termSize":6 }, "schedule": { "interval": "1m" }, "actions": [], "tags": [], "name": "new name", "throttle": null }
The API returns the following:
{ "id": "ac4e6b90-6be7-11eb-ba0d-9b1c1f912d74", "consumer": "alerts", "tags": [], "name": "new name", "enabled": true, "throttle": null, "schedule": { "interval": "1m" }, "params": { "index": [".updated-index"], "timeField": "@timestamp", "groupBy": "top", "aggType": "avg", "timeWindowSize": 5, "timeWindowUnit": "m", "thresholdComparator": ">", "threshold": [1000], "aggField": "sheet.version", "termField": "name.keyword", "termSize": 6 }, "api_key_owner": "elastic", "created_by": "elastic", "updated_by": "elastic", "rule_type_id": ".index-threshold", "scheduled_task_id": "4c5eda00-e74f-11ec-b72f-5b18752ff9ea", "created_at": "2022-12-12T22:43:20.578Z", "updated_at": "2022-12-12T22:44:21.783Z", "notify_when": "onActionGroupChange", "mute_all": false, "muted_alert_ids": [], "execution_status": { "status": "ok", "last_execution_date": "2022-12-12T22:43:21.723Z", "last_duration": 125 }, "actions":[], "last_run":{ "alerts_count": { "new": 0, "ignored": 0, "recovered": 0, "active": 0 }, "outcome_msg" :null, "warning": null, "outcome": "succeeded" }, "next_run": "2022-12-12T22:44:21.653Z" }