Create a rule

Base URL
https://{kibana_url}
  • POST /api/alerting/v2/rules
Auth

Creates a rule with a server-generated identifier. To create or replace a rule with a client-supplied identifier, use PUT /api/alerting/v2/rules/{id}/.

Required privileges

Privileges manage_alerting-v2-rules

Header parameters

kbn-xsrf string required

A required header to protect against CSRF attacks

Request body

kind enum required

Whether the rule creates alerts (alert) or only stores matching events (signal).

Values: alert signal
metadata object required

Rule metadata.

builder_type string · max length: 64

Identifies the rule builder that authored this rule (e.g. "threshold"). Absent for rules authored directly in ES|QL.

description string · max length: 1024

Human-readable description of the rule.

name string · min length: 1 · max length: 256 required

Rule name (must be unique within the space).

owner string · max length: 256

Owner of the rule.

tags string[] · min items: 1 · max items: 20

Tags for categorization, e.g. ["production", "infra"].

no_data_strategy enum

How the rule behaves when it finds no data for a group. If you omit this field or set it to none, those runs are ignored. If you set last_known_status or recover, a standalone query (query.format: standalone) must include query.no_data. A composed query (query.format: composed) uses query.base to detect whether data is present. The emit value is not accepted when creating or updating rules.

Values: last_known_status emit recover none
query union oneOf required

Detection query configuration.

One of: (determined by format)
format: composed

Composed query: a shared base with appendable breach and recovery segments.

format enum required
Values: composed
base string · min length: 1 · max length: 10000 required

Base ES|QL query. Time filters are applied automatically via the lookback window.

recovery_strategy enum

The condition that marks an alert recovered. If omitted or set to none, recovery is disabled: the alert stays active even after the breach query stops returning matches, and state_transition.recovering_count / recovering_timeframe are not allowed. Set to no_breach to recover when the breach query stops returning matches. Set to query only when you also provide query.recovery.

Values: no_breach query none
schedule object required

Execution schedule configuration.

every string · max length: 32 required

Execution interval, e.g. 1m, 5m, 1h.

lookback string · max length: 32

Lookback window for the query, e.g. 5m, 1h. Can also be expressed in ES|QL.

time_field string · min length: 1 · max length: 128 · default: @timestamp

Document field used as the event time when applying the lookback window. Defaults to @timestamp.

Responses

Returns the newly created rule.

application/json
created_at string required

ISO timestamp when the rule was created.

created_by string required nullable

User who created the rule.

enabled boolean required

Whether the rule is enabled.

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
builder_type string · max length: 64

Identifies the rule builder that authored this rule (e.g. "threshold"). Absent for rules authored directly in ES|QL.

description string · max length: 1024

Human-readable description of the rule.

name string · min length: 1 · max length: 256 required

Rule name (must be unique within the space).

owner string · max length: 256

Owner of the rule.

tags string[] · min items: 1 · max items: 20

Tags for categorization, e.g. ["production", "infra"].

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.

no_data_strategy enum

How the rule behaves when it finds no data for a group. If you omit this field or set it to none, those runs are ignored. If you set last_known_status or recover, a standalone query (query.format: standalone) must include query.no_data. A composed query (query.format: composed) uses query.base to detect whether data is present. The emit value is not accepted when creating or updating rules.

Values: last_known_status emit recover none
query union oneOf required

Detection query configuration.

Same options as query
recovery_strategy enum

The condition that marks an alert recovered. If omitted or set to none, recovery is disabled: the alert stays active even after the breach query stops returning matches, and state_transition.recovering_count / recovering_timeframe are not allowed. Set to no_breach to recover when the breach query stops returning matches. Set to query only when you also provide query.recovery.

Values: no_breach query none
schedule object required

Execution schedule configuration.

every string · max length: 32 required

Execution interval, e.g. 1m, 5m, 1h.

lookback string · max length: 32

Lookback window for the query, e.g. 5m, 1h. Can also be expressed in ES|QL.

time_field string · min length: 1 · max length: 128 · default: @timestamp

Document field used as the event time when applying the lookback window. Defaults to @timestamp.

updated_at string required

ISO timestamp when the rule was last updated.

updated_by string required nullable

User who last updated the rule.

version string

The saved object version token of the rule, used for optimistic concurrency control.

Base URL
https://{kibana_url}