[[update-rule-api]]
== Update rule API
++++
<titleabbrev>Update rule</titleabbrev>
++++

Update the attributes for an existing rule.

[NOTE]
====
For the most up-to-date API details, refer to the
{kib-repo}/tree/{branch}/x-pack/plugins/alerting/docs/openapi[open API specification]. For a preview, check out <<rule-apis>>.
====

[[update-rule-api-request]]
=== {api-request-title}

`PUT <kibana host>:<port>/api/alerting/rule/<id>`

`PUT <kibana host>:<port>/s/<space_id>/api/alerting/rule/<id>`

=== {api-prereq-title}

You must have `all` privileges for the appropriate {kib} 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 *{ml-app}*
features, *{observability}*, or *Security* features. If the rule has
`actions`, you must also have `read` privileges for the *Management* >
*{connectors-feature}* feature. For more details, refer to
<<kibana-feature-privileges>>.

=== {api-description-title}

[WARNING]
====
* This API supports only
<<token-api-authentication,token-based authentication>>.
* When you update a rule, it identifies which roles you have at that point in time.
Thereafter, when the rule performs queries, it uses those security privileges.
If you have different privileges than the user that created or most recently
updated the rule, you might change its behavior.
* 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.
====

[[update-rule-api-path-params]]
=== {api-path-parms-title}

`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.

[role="child_attributes"]
[[update-rule-api-request-body]]
=== {api-request-body-title}

`actions`::
(Optional, object array) An array of action objects. The default value is an
empty array (`[]`).
+
.Properties of the action objects:
[%collapsible%open]
=====
`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
<<action-types,connector type>> will receive. The `params` 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`,  or `onThrottleInterval`.

`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
[%collapsible%open]
=====
A schedule uses a `key: value` format. {kib} 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 a `throttle` of `10m` or `1h` will prevent it from sending
90 notifications during this period. The default value is `null`.

[[update-rule-api-response-codes]]
=== {api-response-codes-title}

`200`::
Indicates a successful call.

[[update-rule-api-example]]
=== {api-examples-title}

Update an index threshold rule with ID `ac4e6b90-6be7-11eb-ba0d-9b1c1f912d74`:

[source,sh]
--------------------------------------------------
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
}
--------------------------------------------------
// KIBANA

The API returns the following:

[source,sh]
--------------------------------------------------
{
  "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"
}
--------------------------------------------------