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

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