Update a rule

PUT /api/alerting/rule/{id}

Api key auth Basic auth

Spaces method and path for this operation:

put /s/{space_id}/api/alerting/rule/{id}

Refer to Spaces for more information.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string Required

The identifier for the rule.

application/json

Body

actions array[object]

Default value is [] (empty).
Hide actions attributes Show actions attributes object
An action that runs under defined conditions.
- alerts_filter object
  
  Additional properties are NOT allowed.
  Hide alerts_filter attributes Show alerts_filter attributes object
  
  query object
  
  Additional properties are NOT allowed.
  
  Hide query attributes Show query attributes object
  
  dsl string
  
  A filter written in Elasticsearch Query Domain Specific Language (DSL).
  
  filters array[object] Required
  
  A filter written in Elasticsearch Query Domain Specific Language (DSL) as defined in the kbn-es-query package.
  
  Hide filters attributes Show filters attributes object
  
  $state object
  
  Additional properties are NOT allowed.
  
  Hide $state attribute Show $state attribute object
  
  store string Required
  
  A filter that can be applied to a specific application context or applied globally.
  
  Values are appState or globalState.
  
  meta object Required
  
  query object
  
  kql string Required
  
  A filter written in Kibana Query Language (KQL).
  
  timeframe object
  
  Defines a period that limits whether the action runs.
  
  Additional properties are NOT allowed.
  
  Hide timeframe attributes Show timeframe attributes object
  
  days array[integer] Required
  
  Defines the days of the week that the action can run, represented as an array of numbers. For example, 1 represents Monday. An empty array is equivalent to specifying all the days of the week.
  
  Values are 1, 2, 3, 4, 5, 6, or 7.
  
  hours object Required
  
  Defines the range of time in a day that the action can run. If the start value is 00:00 and the end value is 24:00, actions be generated all day.
  
  Additional properties are NOT allowed.
  
  Hide hours attributes Show hours attributes object
  
  end string Required
  
  The end of the time frame, in 24-hour notation (hh:mm).
  
  start string Required
  
  The start of the time frame, in 24-hour notation (hh:mm).
  
  timezone string Required
  
  The ISO time zone for the hours values. Values such as UTC and UTC+1 also work but lack built-in support for daylight savings time and are not recommended.
- frequency object
  
  Additional properties are NOT allowed.
  Hide frequency attributes Show frequency attributes object
  
  notify_when string Required
  
  Indicates how frequently rule actions are triggered. Valid values include: onActionGroupChange: Actions run when the alert status changes; onActiveAlert: Actions run when the alert becomes active and at each check interval while the rule conditions are met; onThrottleInterval: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. You cannot specify notify_when at both the rule and action level. The recommended approach is to set it for each action individually. If you set notify_when at the rule level and then edit the rule, it will automatically be converted to action-specific values.
  
  Values are onActionGroupChange, onActiveAlert, or onThrottleInterval.
  
  summary boolean Required
  
  Indicates whether the action is a summary.
  
  throttle string | null Required
  
  The throttle interval defines how frequently rule actions are triggered. It is specified in seconds, minutes, hours, or days and only applies when notify_when is set to onThrottleInterval. You cannot set the throttle interval at both the rule and action level. The recommended approach is to set it for each action individually. If you set the throttle interval at the rule level and then edit the rule, it will automatically be converted to action-specific values.
- group string
  
  The group name, which affects when the action runs (for example, when the threshold is met or when the alert is recovered). Each rule type has a list of valid action group names. If you don't need to group actions, set to default.
- id string Required
  
  The identifier for the connector saved object.
- params object
  
  The parameters for the action, which are sent to the connector. The params are handled as Mustache templates and passed a default set of context.
  
  Default value is {} (empty).
- use_alert_data_for_template boolean
  
  Indicates whether to use alert data as a template.
- uuid string
  
  A universally unique identifier (UUID) for the action.
alert_delay object

Indicates that an alert occurs only when the specified number of consecutive runs met the rule conditions.

Additional properties are NOT allowed.
Hide alert_delay attribute Show alert_delay attribute object
- active number Required
  
  The number of consecutive runs that must meet the rule conditions.
artifacts object

Additional properties are NOT allowed.
Hide artifacts attributes Show artifacts attributes object
- dashboards array[object]
  
  Not more than 10 elements.
  Hide dashboards attribute Show dashboards attribute object
  
  id string Required
- investigation_guide object
  
  Additional properties are NOT allowed.
  Hide investigation_guide attribute Show investigation_guide attribute object
  
  blob string Required
  
  Maximum length is 10000.
flapping object

When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.

Additional properties are NOT allowed.
Hide flapping attributes Show flapping attributes object
- enabled boolean
  
  Determines whether the rule can enter the flapping state. By default, rules can enter the flapping state.
- look_back_window number Required
  
  The minimum number of runs in which the threshold must be met.
  
  Minimum value is 2, maximum value is 20.
- status_change_threshold number Required
  
  The minimum number of times an alert must switch states within the defined look back window time.
  
  Minimum value is 2, maximum value is 20.
name string Required

The name of the rule. While this name does not have to be unique, a distinctive name can help you identify a rule.
notify_when string | null

Indicates how frequently rule actions are triggered. Valid values include: onActionGroupChange: Actions run when the alert status changes; onActiveAlert: Actions run when the alert becomes active and at each check interval while the rule conditions are met; onThrottleInterval: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. You cannot specify notify_when at both the rule and action level. The recommended approach is to set it for each action individually. If you set notify_when at the rule level and then edit the rule, it will automatically be converted to action-specific values.

Values are onActionGroupChange, onActiveAlert, or onThrottleInterval.
params object

The parameters for the rule.

Default value is {} (empty).
schedule object Required

Additional properties are NOT allowed.
Hide schedule attribute Show schedule attribute object
- interval string Required
  
  The interval is specified in seconds, minutes, hours, or days.
tags array[string]

The tags for the rule.

Default value is [] (empty).
throttle string | null

Use the throttle property in the action frequency object instead. The throttle interval, which defines how frequently rule actions are triggered. You cannot specify the throttle interval at both the rule and action level. If you set the throttle interval at the rule level and then edit the rule, it will automatically be converted to action-specific values.

Responses

200 application/json

Indicates a successful call.
Hide response attributes Show response attributes object
- actions array[object] Required
  
  Hide actions attributes Show actions attributes object
  
  alerts_filter object
  
  Defines a period that limits whether the action runs.
  
  Additional properties are NOT allowed.
  
  Hide alerts_filter attributes Show alerts_filter attributes object
  
  query object
  
  Additional properties are NOT allowed.
  
  Hide query attributes Show query attributes object
  
  dsl string
  
  A filter written in Elasticsearch Query Domain Specific Language (DSL).
  
  filters array[object] Required
  
  A filter written in Elasticsearch Query Domain Specific Language (DSL) as defined in the kbn-es-query package.
  
  Hide filters attributes Show filters attributes object
  
  $state object
  
  Additional properties are NOT allowed.
  
  Hide $state attribute Show $state attribute object
  
  store string Required
  
  A filter that can be applied to a specific application context or applied globally.
  
  Values are appState or globalState.
  
  meta object Required
  
  query object
  
  kql string Required
  
  A filter written in Kibana Query Language (KQL).
  
  timeframe object
  
  Additional properties are NOT allowed.
  
  Hide timeframe attributes Show timeframe attributes object
  
  days array[integer] Required
  
  Defines the days of the week that the action can run, represented as an array of numbers. For example, 1 represents Monday. An empty array is equivalent to specifying all the days of the week.
  
  Values are 1, 2, 3, 4, 5, 6, or 7.
  
  hours object Required
  
  Additional properties are NOT allowed.
  
  Hide hours attributes Show hours attributes object
  
  end string Required
  
  The end of the time frame, in 24-hour notation (hh:mm).
  
  start string Required
  
  The start of the time frame, in 24-hour notation (hh:mm).
  
  timezone string Required
  
  The ISO time zone for the hours values. Values such as UTC and UTC+1 also work but lack built-in support for daylight savings time and are not recommended.
  
  connector_type_id string Required
  
  The type of connector. This property appears in responses but cannot be set in requests.
  
  frequency object
  
  Additional properties are NOT allowed.
  
  Hide frequency attributes Show frequency attributes object
  
  notify_when string Required
  
  Indicates how frequently rule actions are triggered. Valid values include: onActionGroupChange: Actions run when the alert status changes; onActiveAlert: Actions run when the alert becomes active and at each check interval while the rule conditions are met; onThrottleInterval: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. You cannot specify notify_when at both the rule and action level. The recommended approach is to set it for each action individually. If you set notify_when at the rule level and then edit the rule, it will automatically be converted to action-specific values.
  
  Values are onActionGroupChange, onActiveAlert, or onThrottleInterval.
  
  summary boolean Required
  
  Indicates whether the action is a summary.
  
  throttle string | null Required
  
  The throttle interval defines how frequently rule actions are triggered. It is specified in seconds, minutes, hours, or days and only applies when 'notify_when' is set to 'onThrottleInterval'. You cannot set the throttle interval at both the rule and action level. The recommended approach is to set it for each action individually. If you set the throttle interval at the rule level and then edit the rule, it will automatically be converted to action-specific values.
  
  group string
  
  The group name, which affects when the action runs (for example, when the threshold is met or when the alert is recovered). Each rule type has a list of valid action group names. If you don't need to group actions, set to default.
  
  id string Required
  
  The identifier for the connector saved object.
  
  params object Required
  
  The parameters for the action, which are sent to the connector. The params are handled as Mustache templates and passed a default set of context.
  
  use_alert_data_for_template boolean
  
  Indicates whether to use alert data as a template.
  
  uuid string
  
  A universally unique identifier (UUID) for the action.
- alert_delay object
  
  Indicates that an alert occurs only when the specified number of consecutive runs met the rule conditions.
  
  Additional properties are NOT allowed.
  
  Hide alert_delay attribute Show alert_delay attribute object
  
  active number Required
  
  The number of consecutive runs that must meet the rule conditions.
- api_key_created_by_user boolean | null
  
  Indicates whether the API key that is associated with the rule was created by the user.
- api_key_owner string | null Required
  
  The owner of the API key that is associated with the rule and used to run background tasks.
- artifacts object
  
  Additional properties are NOT allowed.
  
  Hide artifacts attributes Show artifacts attributes object
  
  dashboards array[object]
  
  Hide dashboards attribute Show dashboards attribute object
  
  id string Required
  
  investigation_guide object
  
  Additional properties are NOT allowed.
  
  Hide investigation_guide attribute Show investigation_guide attribute object
  
  blob string Required
  
  User-created content that describes alert causes and remediation.
- consumer string Required
  
  The name of the application or feature that owns the rule. For example: alerts, apm, discover, infrastructure, logs, metrics, ml, monitoring, securitySolution, siem, stackAlerts, or uptime.
- created_at string Required
  
  The date and time that the rule was created.
- created_by string | null Required
  
  The identifier for the user that created the rule.
- enabled boolean Required
  
  Indicates whether you want the rule to run on an interval basis after it is created.
- execution_status object Required
  
  Additional properties are NOT allowed.
  
  Hide execution_status attributes Show execution_status attributes object
  
  error object
  
  Additional properties are NOT allowed.
  
  Hide error attributes Show error attributes object
  
  message string Required
  
  Error message.
  
  reason string Required
  
  Reason for error.
  
  Values are read, decrypt, execute, unknown, license, timeout, disabled, or validate.
  
  last_duration number
  
  Duration of last rule execution.
  
  last_execution_date string Required
  
  The date and time of the last rule execution.
  
  status string Required
  
  Status of rule execution.
  
  Values are ok, active, error, warning, pending, or unknown.
  
  warning object
  
  Additional properties are NOT allowed.
  
  Hide warning attributes Show warning attributes object
  
  message string Required
  
  Warning message.
  
  reason string Required
  
  Reason for warning.
  
  Values are maxExecutableActions, maxAlerts, maxQueuedActions, or ruleExecution.
- flapping object
  
  When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.
  
  Additional properties are NOT allowed.
  
  Hide flapping attributes Show flapping attributes object
  
  enabled boolean
  
  Determines whether the rule can enter the flapping state. By default, rules can enter the flapping state.
  
  look_back_window number Required
  
  The minimum number of runs in which the threshold must be met.
  
  Minimum value is 2, maximum value is 20.
  
  status_change_threshold number Required
  
  The minimum number of times an alert must switch states within the defined look back window time.
  
  Minimum value is 2, maximum value is 20.
- id string Required
  
  The identifier for the rule.
- last_run object | null
  
  Additional properties are NOT allowed.
  
  Hide last_run attributes Show last_run attributes object | null
  
  alerts_count object Required
  
  Additional properties are NOT allowed.
  
  Hide alerts_count attributes Show alerts_count attributes object
  
  active number | null
  
  Number of active alerts during last run.
  
  ignored number | null
  
  Number of ignored alerts during last run.
  
  new number | null
  
  Number of new alerts during last run.
  
  recovered number | null
  
  Number of recovered alerts during last run.
  
  outcome string Required
  
  Outcome of the last rule run. Value can be succeeded, warning, or failed.
  
  Values are succeeded, warning, or failed.
  
  outcome_msg array[string] | null
  
  Outcome message generated during last rule run.
  
  outcome_order number
  
  Order of the outcome.
  
  warning string | null
  
  Warning of last rule execution.
  
  Values are read, decrypt, execute, unknown, license, timeout, disabled, validate, maxExecutableActions, maxAlerts, maxQueuedActions, or ruleExecution.
- mapped_params object
- mute_all boolean Required
  
  Indicates whether all alerts are muted.
- muted_alert_ids array[string] Required
  
  List of identifiers of muted alerts.
- name string Required
  
  The name of the rule.
- next_run string | null
  
  Date and time of the next rule run.
- notify_when string | null
  
  Indicates how frequently rule actions are triggered. Valid values include: onActionGroupChange: Actions run when the alert status changes; onActiveAlert: Actions run when the alert becomes active and at each check interval while the rule conditions are met; onThrottleInterval: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. You cannot specify notify_when at both the rule and action level. The recommended approach is to set it for each action individually. If you set notify_when at the rule level and then edit the rule, it will automatically be converted to action-specific values.
  
  Values are onActionGroupChange, onActiveAlert, or onThrottleInterval.
- params object Required
  
  The parameters for the rule.
- revision number Required
  
  The rule revision number.
- rule_type_id string Required
  
  The rule type identifier.
- running boolean | null
  
  Indicates whether the rule is running.
- schedule object Required
  
  Additional properties are NOT allowed.
  
  Hide schedule attribute Show schedule attribute object
  
  interval string Required
  
  The interval is specified in seconds, minutes, hours, or days.
- scheduled_task_id string
  
  Identifier of the scheduled task.
- tags array[string] Required
  
  The tags for the rule.
- throttle string | null Deprecated
  
  Deprecated in 8.13.0. Use the throttle property in the action frequency object instead. The throttle interval, which defines how frequently rule actions are triggered. You cannot specify the throttle interval at both the rule and action level. If you set the throttle interval at the rule level and then edit the rule, it will automatically be converted to action-specific values.
- updated_at string Required
  
  The date and time of the latest updates to the rule.
- updated_by string | null Required
  
  The identifier for the user who was the last to update the rule.
400

Indicates an invalid schema or parameters.
403

Indicates that this call is forbidden.
404

Indicates a rule with the given ID does not exist.
409

Indicates that the rule has already been updated by another user.

PUT /api/alerting/rule/{id}

curl \
 --request PUT 'https://localhost:5601/api/alerting/rule/{id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"actions":[{"frequency":{"notify_when":"onActionGroupChange","summary":false},"group":"threshold met","id":"96b668d0-a1b6-11ed-afdf-d39a49596974","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}}"}}],"name":"new name","params":{"aggField":"sheet.version","aggType":"avg","groupBy":"top","index":[".updated-index"],"termField":"name.keyword","termSize":6,"threshold":[1000],"thresholdComparator":"\u003e","timeField":"@timestamp","timeWindowSize":5,"timeWindowUnit":"m"},"schedule":{"interval":"1m"},"tags":[]}'

Request example

Update an index threshold rule that uses a server log connector to send notifications when the threshold is met.

{
  "actions": [
    {
      "frequency": {
        "notify_when": "onActionGroupChange",
        "summary": false
      },
      "group": "threshold met",
      "id": "96b668d0-a1b6-11ed-afdf-d39a49596974",
      "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}}"
      }
    }
  ],
  "name": "new name",
  "params": {
    "aggField": "sheet.version",
    "aggType": "avg",
    "groupBy": "top",
    "index": [
      ".updated-index"
    ],
    "termField": "name.keyword",
    "termSize": 6,
    "threshold": [
      1000
    ],
    "thresholdComparator": ">",
    "timeField": "@timestamp",
    "timeWindowSize": 5,
    "timeWindowUnit": "m"
  },
  "schedule": {
    "interval": "1m"
  },
  "tags": []
}

Response examples (200)

The response for successfully updating an index threshold rule.

{
  "actions": [
    {
      "connector_type_id": ".server-log",
      "frequency": {
        "notify_when": "onActionGroupChange",
        "summary": false,
        "throttle": null
      },
      "group": "threshold met",
      "id": "96b668d0-a1b6-11ed-afdf-d39a49596974",
      "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}"
      },
      "uuid": "07aef2a0-9eed-4ef9-94ec-39ba58eb609d"
    }
  ],
  "api_key_created_by_user": false,
  "api_key_owner": "elastic",
  "consumer": "alerts",
  "created_at": "2024-03-26T23:13:20.985Z",
  "created_by": "elastic",
  "enabled": true,
  "execution_status": {
    "last_duration": 52,
    "last_execution_date": "2024-03-26T23:22:51.390Z",
    "status": "ok"
  },
  "id": "ac4e6b90-6be7-11eb-ba0d-9b1c1f912d74",
  "last_run": {
    "alerts_count": {
      "active": 0,
      "ignored": 0,
      "new": 0,
      "recovered": 0
    },
    "outcome": "succeeded",
    "outcome_msg": null,
    "warning": null
  },
  "mute_all": false,
  "muted_alert_ids": [],
  "name": "new name",
  "next_run": "2024-03-26T23:23:51.316Z",
  "params": {
    "aggField": "sheet.version",
    "aggType": "avg",
    "groupBy": "top",
    "index": [
      ".updated-index"
    ],
    "termField": "name.keyword",
    "termSize": 6,
    "threshold": [
      1000
    ],
    "thresholdComparator": ">",
    "timeField": "@timestamp",
    "timeWindowSize": 5,
    "timeWindowUnit": "m"
  },
  "revision": 1,
  "rule_type_id": ".index-threshold",
  "running": false,
  "schedule": {
    "interval": "1m"
  },
  "scheduled_task_id": "4c5eda00-e74f-11ec-b72f-5b18752ff9ea",
  "tags": [],
  "throttle": null,
  "updated_at": "2024-03-26T23:22:59.949Z",
  "updated_by": "elastic"
}