Create or replace a rule

Base URL: https://{kibana_url}

PUT /api/alerting/v2/rules/{id}
PUT /s/{space_id}/api/alerting/v2/rules/{id}

Auth

Creates a rule with the given identifier, or fully replaces it if one already exists.

Required privileges

Privileges manage_alerting-v2-rules

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 · min length: 1 · max length: 150 · pattern: ^[a-zA-Z0-9_-]+$ required: The identifier for the rule. Chosen at creation and permanent — it cannot be changed afterwards. Re-using the id of a deleted resource is allowed but discouraged: execution history, change history, and alerts recorded under that id are retained and are attributed to the new resource. Ids appear in URLs and logs, so keep them free of sensitive data.

Header parameters

kbn-xsrf string required: A required header to protect against CSRF attacks

Request body

artifacts object[] · min items: 1 · max items: 100: Optional objects attached to the rule, such as a runbook or a dashboard. Each item has id, type, and data. The shape of data depends on type. For example, a runbook uses content and a dashboard uses dashboard_id. Known types are validated against that shape. Unknown types are stored when id, type, and data are present. An empty array is rejected: omit artifacts on create, or send null on PATCH to clear.
enabled boolean: Whether the rule is enabled. On create, defaults to true when omitted. On replace, omitting this field preserves the existing enabled state.
grouping object: Grouping configuration.
kind enum required: Whether the rule creates alerts (alert) or only stores matching events (signal).; Values: alert signal
metadata object required: Rule metadata.
no_data union oneOf: What the rule does when a group has no data. Required when kind is alert. Not allowed when kind is signal. Any strategy other than ignore requires either query.breach or no_data.query, so that a group with no data can be told apart from one that stopped breaching.; One of: (determined by strategy)
query object required: ES|QL query the rule evaluates. base is required. breach is an optional clause appended to it.
recovery union oneOf: When an alert recovers. Required when kind is alert. Not allowed when kind is signal.; One of: (determined by strategy)
schedule object required: Execution schedule configuration.
state_transition object: Specifies how many consecutive matches, or how long a condition must hold, before an alert becomes active or inactive. Allowed only when kind is alert.
time_field string · min length: 1 · max length: 256 · default: @timestamp: Document field Kibana uses with schedule.lookback to time-filter query.base.

Responses

Returns the replaced rule.

application/json

artifacts object[] · min items: 1 · max items: 100: Optional objects attached to the rule, such as a runbook or a dashboard. Each item has id, type, and data. The shape of data depends on type. For example, a runbook uses content and a dashboard uses dashboard_id. Known types are validated against that shape. Unknown types are stored when id, type, and data are present. An empty array is rejected: omit artifacts on create, or send null on PATCH to clear.
created_at string · format: date-time · max length: 64 required: ISO timestamp when the rule was created.
created_by object required: Actor who created the rule.
enabled boolean required: Whether the rule is enabled.
grouping object: Grouping configuration.
id string required: Unique rule identifier.
kind enum required: Whether the rule creates alerts (alert) or only stores matching events (signal).; Values: alert signal
metadata object required: Rule metadata.
no_data union oneOf: What the rule does when a group has no data. Required when kind is alert. Not allowed when kind is signal. Any strategy other than ignore requires either query.breach or no_data.query, so that a group with no data can be told apart from one that stopped breaching.; One of: (determined by strategy)
query object required: ES|QL query the rule evaluates. base is required. breach is an optional clause appended to it.
recovery union oneOf: When an alert recovers. Required when kind is alert. Not allowed when kind is signal.; One of: (determined by strategy)
schedule object required: Execution schedule configuration.
state_transition object: Specifies how many consecutive matches, or how long a condition must hold, before an alert becomes active or inactive. Allowed only when kind is alert.
time_field string · min length: 1 · max length: 256 · default: @timestamp: Document field Kibana uses with schedule.lookback to time-filter query.base.
updated_at string · format: date-time · max length: 64 required: ISO timestamp when the rule was last updated.
updated_by object required: Actor who last updated the rule.
version integer · min: 1 · max: 9007199254740991 required: Monotonically increasing integer number representing a rule configuration version, incremented on every change. Used on generated rule events as rule.version.

Returns the newly created rule.

application/json

artifacts object[] · min items: 1 · max items: 100: Optional objects attached to the rule, such as a runbook or a dashboard. Each item has id, type, and data. The shape of data depends on type. For example, a runbook uses content and a dashboard uses dashboard_id. Known types are validated against that shape. Unknown types are stored when id, type, and data are present. An empty array is rejected: omit artifacts on create, or send null on PATCH to clear.
created_at string · format: date-time · max length: 64 required: ISO timestamp when the rule was created.
created_by object required: Actor who created the rule.
enabled boolean required: Whether the rule is enabled.
grouping object: Grouping configuration.
id string required: Unique rule identifier.
kind enum required: Whether the rule creates alerts (alert) or only stores matching events (signal).; Values: alert signal
metadata object required: Rule metadata.
no_data union oneOf: What the rule does when a group has no data. Required when kind is alert. Not allowed when kind is signal. Any strategy other than ignore requires either query.breach or no_data.query, so that a group with no data can be told apart from one that stopped breaching.; One of: (determined by strategy)
query object required: ES|QL query the rule evaluates. base is required. breach is an optional clause appended to it.
recovery union oneOf: When an alert recovers. Required when kind is alert. Not allowed when kind is signal.; One of: (determined by strategy)
schedule object required: Execution schedule configuration.
state_transition object: Specifies how many consecutive matches, or how long a condition must hold, before an alert becomes active or inactive. Allowed only when kind is alert.
time_field string · min length: 1 · max length: 256 · default: @timestamp: Document field Kibana uses with schedule.lookback to time-filter query.base.
updated_at string · format: date-time · max length: 64 required: ISO timestamp when the rule was last updated.
updated_by object required: Actor who last updated the rule.
version integer · min: 1 · max: 9007199254740991 required: Monotonically increasing integer number representing a rule configuration version, incremented on every change. Used on generated rule events as rule.version.

Indicates an invalid schema or parameters.

application/json

Indicates the request was not authenticated.

application/json

Indicates the user does not have the required privileges to perform the request.

application/json

Indicates the rule was created or updated concurrently, or the request changes immutable fields.

application/json

Indicates an unexpected server-side error.

application/json

Indicates the alerting engine is disabled by the alerting:v2:enabled advanced setting.

application/json

Required privileges

Path parameters

Header parameters

Request body { }

Responses

Request body