Update a rule

Base URL
https://{kibana_url}
Auth

Path parameters

space_id string optional

An identifier for the space. If space_id is not provided in the URL, the default space is used. Refer to Spaces for more information.

id string required

The identifier for the rule.

Header parameters

kbn-xsrf string required

A required header to protect against CSRF attacks

Request body

actions object[] · default: []
alerts_filter object
query object
dsl string

A filter written in Elasticsearch Query Domain Specific Language (DSL).

filters object[] required

A filter written in Elasticsearch Query Domain Specific Language (DSL) as defined in the kbn-es-query package.

$state object
store enum required

A filter that can be applied to a specific application context or applied globally.

Values: appState globalState
meta map string to object required
query map string to object
kql string required

A filter written in Kibana Query Language (KQL).

timeframe object

Defines a period that limits whether the action runs.

days enum[] 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: 1 2 3 4 5 6 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.

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
notify_when enum 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: onActionGroupChange onActiveAlert onThrottleInterval
summary boolean required

Indicates whether the action is a summary.

throttle string · default: null nullable

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 map string to object · default: {}

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.

active number required

The number of consecutive runs that must meet the rule conditions.

artifacts object
dashboards object[] · max items: 10
id string required
investigation_guide object
blob string · max length: 10000 required
flapping object
enabled boolean

Determines whether the rule can enter the flapping state. By default, rules can enter the flapping state.

look_back_window number · min: 2 · max: 20 required

The minimum number of runs in which the threshold must be met.

status_change_threshold number · min: 2 · max: 20 required

The minimum number of times an alert must switch states within the defined look back window time.

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 enum nullable

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: onActionGroupChange onActiveAlert onThrottleInterval null
params map string to object · default: {}

The parameters for the rule.

schedule object required
interval string required

The interval is specified in seconds, minutes, hours, or days.

tags string[] · default: []
throttle string nullable

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

Indicates a successful call.

application/json
actions object[] required
alerts_filter object

Defines a period that limits whether the action runs.

query object
dsl string

A filter written in Elasticsearch Query Domain Specific Language (DSL).

filters object[] required

A filter written in Elasticsearch Query Domain Specific Language (DSL) as defined in the kbn-es-query package.

$state object
store enum required

A filter that can be applied to a specific application context or applied globally.

Values: appState globalState
meta map string to object required
query map string to object
kql string required

A filter written in Kibana Query Language (KQL).

timeframe object
days enum[] 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: 1 2 3 4 5 6 7
hours object required
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
notify_when enum 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: onActionGroupChange onActiveAlert onThrottleInterval
summary boolean required

Indicates whether the action is a summary.

throttle string · default: null nullable

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 map string to 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.

active number required

The number of consecutive runs that must meet the rule conditions.

api_key_created_by_user boolean nullable

Indicates whether the API key that is associated with the rule was created by the user.

api_key_owner string · default: null nullable

The owner of the API key that is associated with the rule and used to run background tasks.

artifacts object
dashboards object[]
id string required
investigation_guide 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 · default: null nullable

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
error object
message string required

Error message.

reason enum required

Reason for error.

Values: read decrypt execute unknown license timeout disabled validate
last_duration number

Duration of last rule execution.

last_execution_date string required

The date and time of the last rule execution.

status enum required

Status of rule execution.

Values: ok active error warning pending unknown
warning object
message string required

Warning message.

reason enum required

Reason for warning.

Values: maxExecutableActions maxAlerts maxQueuedActions ruleExecution
flapping object
enabled boolean

Determines whether the rule can enter the flapping state. By default, rules can enter the flapping state.

look_back_window number · min: 2 · max: 20 required

The minimum number of runs in which the threshold must be met.

status_change_threshold number · min: 2 · max: 20 required

The minimum number of times an alert must switch states within the defined look back window time.

id string required

The identifier for the rule.

last_run object nullable
alerts_count object required
active number nullable

Number of active alerts during last run.

ignored number nullable

Number of ignored alerts during last run.

new number nullable

Number of new alerts during last run.

recovered number nullable

Number of recovered alerts during last run.

outcome enum required

Outcome of the last rule run. Value can be succeeded, warning, or failed.

Values: succeeded warning failed
outcome_msg string[] nullable
outcome_order number

Order of the outcome.

warning enum nullable

Warning of last rule execution.

Values: read decrypt execute unknown license timeout disabled validate maxExecutableActions maxAlerts maxQueuedActions ruleExecution null
mapped_params map string to object
mute_all boolean required

Indicates whether all alerts are muted.

muted_alert_ids string[] required
name string required

The name of the rule.

next_run string nullable

Date and time of the next rule run.

notify_when enum nullable

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: onActionGroupChange onActiveAlert onThrottleInterval null
params map string to 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 nullable

Indicates whether the rule is running.

schedule object required
interval string required

The interval is specified in seconds, minutes, hours, or days.

scheduled_task_id string

Identifier of the scheduled task.

tags string[] required
throttle string nullable 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 · default: null nullable

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.

Base URL
https://{kibana_url}