Update a rule
- Base URL
-
https://{kibana_url}
Refer to Spaces for more information.
Apply a partial update. A field you omit keeps its stored value, and that applies at every level: send {"metadata": {"name": "Disk pressure"}} to change one leaf while leaving its siblings alone. Send null to clear a field, again at any level: {"metadata": {"description": null}} clears a single leaf, while {"grouping": null} clears a whole object. Lists and variant objects are replaced as a unit rather than merged, since a partly-sent variant could never be valid. The merged result is validated as a whole, so a patch that would leave the resource invalid is rejected with a 400 and nothing is stored.
Required authorization
- Privileges manage_alerting-v2-rules
Path parameters
-
idstring · 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.
Request body
-
artifactsobject · min items: 1 · max items: 100nullable -
Optional objects attached to the rule, such as a runbook or a dashboard. Each item has
id,type, anddata. The shape ofdatadepends ontype. For example, arunbookusescontentand adashboardusesdashboard_id. Known types are validated against that shape. Unknown types are stored whenid,type, anddataare present. An empty array is rejected: omitartifactson create, or sendnullon PATCH to clear. -
metadataobject -
Rule metadata.
-
builderobjectnullable -
Identifies the rule builder that authored this rule (e.g. "threshold"). Absent for rules authored directly in ES|QL; send
nullon PATCH to clear it. -
descriptionstring · min length: 1 · max length: 1024nullable -
Human-readable description of the rule. Omit to leave it unset; send
nullon PATCH to clear it. An empty string is rejected. -
Routing tags that link alerts from this rule to action policies. An action policy applies when its
matcher.tagscontains at least one of these tags. Only allowed when kind is "alert". -
Tags for categorization, e.g. ["production", "infra"].
-
no_dataunion -
What the rule does when a group has no data. Required when
kindisalert. Not allowed whenkindissignal. Any strategy other thanignorerequires eitherquery.breachorno_data.query, so that a group with no data can be told apart from one that stopped breaching. -
queryobject -
ES|QL query the rule evaluates.
baseis required.breachis an optional clause appended to it. -
recoveryunion -
When an alert recovers. Required when
kindisalert. Not allowed whenkindissignal. -
state_transitionobject -
Specifies how many consecutive matches, or how long a condition must hold, before an alert becomes
activeorinactive. Allowed only whenkindisalert. -
pendingobject -
Delay before a match opens an alert.
-
recoveringobject -
Delay before a recovered match closes the alert. Has no effect when
recovery.strategyismanual.
Responses
Returns the updated rule.
-
artifactsobject · min items: 1 · max items: 100 -
Optional objects attached to the rule, such as a runbook or a dashboard. Each item has
id,type, anddata. The shape ofdatadepends ontype. For example, arunbookusescontentand adashboardusesdashboard_id. Known types are validated against that shape. Unknown types are stored whenid,type, anddataare present. An empty array is rejected: omitartifactson create, or sendnullon PATCH to clear. -
kindrequired -
Whether the rule creates alerts (
alert) or only stores matching events (signal). -
Values:
alertsignal -
metadataobjectrequired -
Rule metadata.
-
builderobject -
Identifies the rule builder that authored this rule (e.g. "threshold"). Absent for rules authored directly in ES|QL; send
nullon PATCH to clear it. -
descriptionstring · min length: 1 · max length: 1024 -
Human-readable description of the rule. Omit to leave it unset; send
nullon PATCH to clear it. An empty string is rejected. -
Routing tags that link alerts from this rule to action policies. An action policy applies when its
matcher.tagscontains at least one of these tags. Only allowed when kind is "alert". -
Tags for categorization, e.g. ["production", "infra"].
-
no_dataoneOf -
What the rule does when a group has no data. Required when
kindisalert. Not allowed whenkindissignal. Any strategy other thanignorerequires eitherquery.breachorno_data.query, so that a group with no data can be told apart from one that stopped breaching. -
queryobjectrequired -
ES|QL query the rule evaluates.
baseis required.breachis an optional clause appended to it. -
recoveryoneOf -
When an alert recovers. Required when
kindisalert. Not allowed whenkindissignal. -
state_transitionobject -
Specifies how many consecutive matches, or how long a condition must hold, before an alert becomes
activeorinactive. Allowed only whenkindisalert. -
pendingobject -
recoveringobject -
time_fieldstring · min length: 1 · max length: 256 · default: @timestamp -
Document field Kibana uses with
schedule.lookbackto time-filterquery.base.
Indicates an invalid schema or parameters.
Indicates the request was not authenticated.
Indicates the user does not have the required privileges to perform the request.
Indicates a rule with the given ID does not exist.
Indicates the rule was concurrently updated by another caller.
Indicates an unexpected server-side error.
Indicates the alerting engine is disabled by the alerting:v2:enabled advanced setting.