Create a rule

Base URL
https://{kibana_url}
  • POST /api/alerting/v2/rules
  • POST /s/{space_id}/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

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.

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.

data map string to object required

Structured artifact data.

id string · min length: 1 · max length: 150 required

Artifact identifier.

type string · min length: 1 · max length: 128 required

Artifact type.

grouping object

Grouping configuration.

fields string[] · min items: 1 · max items: 16 required

Fields to group alerts by, e.g. ["host.name", "service.name"]. Should match ES|QL GROUP BY fields.

kind enum required

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

Values: alert signal
metadata object required

Rule metadata.

builder object

Identifies the rule builder that authored this rule (e.g. "threshold"). Absent for rules authored directly in ES|QL; send null on PATCH to clear it.

type string · min length: 1 · max length: 64 required

Rule builder type.

description string · min length: 1 · max length: 1024

Human-readable description of the rule. Omit to leave it unset; send null on PATCH to clear it. An empty string is rejected.

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

Rule name (must be unique within the space).

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

Routing tags that link alerts from this rule to action policies. An action policy applies when its matcher.tags contains at least one of these tags. Only allowed when kind is "alert".

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

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

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)
strategy: ignore

Does not check whether a group still has data. Missing groups do not produce no_data events.

strategy enum required
Values: ignore
query object required

ES|QL query the rule evaluates. base is required. breach is an optional clause appended to it.

base string · min length: 1 · max length: 10000 required

ES|QL query that specifies the data to evaluate. Must include a FROM clause. Kibana applies the time filter from schedule.lookback using time_field.

breach object

Optional ES|QL clause appended to query.base. If omitted, every row from query.base is a match, and a no_data strategy other than ignore then requires no_data.query.

segment string · min length: 1 · max length: 10000 required

ES|QL clause appended to query.base, for example WHERE avg_cpu > 0.85. Don't include a FROM clause.

recovery union oneOf

When an alert recovers. Required when kind is alert. Not allowed when kind is signal.

One of: (determined by strategy)
strategy: no_breach

Recovers the alert when its group no longer appears in the breach results.

strategy enum required
Values: no_breach
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.

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.

pending object
count integer · min: 0 · max: 1000

Consecutive matches the alert spends in pending before it becomes active on the next match. For example, 2 opens it on the third consecutive match. Set to 0 to open it on the first match.

operator enum

When both count and timeframe are set, and requires both and or requires either. Allowed only when both fields are present.

Values: and or
timeframe string · max length: 32

Duration the condition must hold, for example 5m. Combine with count using operator.

recovering object
count integer · min: 0 · max: 1000

Consecutive recoveries the alert spends in recovering before it becomes inactive on the next recovery. For example, 2 closes it on the third consecutive recovery. Set to 0 to close it on the first recovery.

operator enum

When both count and timeframe are set, and requires both and or requires either. Allowed only when both fields are present.

Values: and or
timeframe string · max length: 32

Duration the condition must hold, for example 5m. Combine with count using operator.

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 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.

data map string to object required

Structured artifact data.

id string · min length: 1 · max length: 150 required

Artifact identifier.

type string · min length: 1 · max length: 128 required

Artifact type.

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.

profile_uid string required nullable

User profile ID of the actor, or null when it cannot be resolved.

enabled boolean required

Whether the rule is enabled.

grouping object

Grouping configuration.

fields string[] · min items: 1 · max items: 16 required

Fields to group alerts by, e.g. ["host.name", "service.name"]. Should match ES|QL GROUP BY fields.

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.

builder object

Identifies the rule builder that authored this rule (e.g. "threshold"). Absent for rules authored directly in ES|QL; send null on PATCH to clear it.

type string · min length: 1 · max length: 64 required

Rule builder type.

description string · min length: 1 · max length: 1024

Human-readable description of the rule. Omit to leave it unset; send null on PATCH to clear it. An empty string is rejected.

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

Rule name (must be unique within the space).

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

Routing tags that link alerts from this rule to action policies. An action policy applies when its matcher.tags contains at least one of these tags. Only allowed when kind is "alert".

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

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

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)
strategy: ignore

Does not check whether a group still has data. Missing groups do not produce no_data events.

strategy enum required
Values: ignore
query object required

ES|QL query the rule evaluates. base is required. breach is an optional clause appended to it.

base string · min length: 1 · max length: 10000 required

ES|QL query that specifies the data to evaluate. Must include a FROM clause. Kibana applies the time filter from schedule.lookback using time_field.

breach object

Optional ES|QL clause appended to query.base. If omitted, every row from query.base is a match, and a no_data strategy other than ignore then requires no_data.query.

segment string · min length: 1 · max length: 10000 required

ES|QL clause appended to query.base, for example WHERE avg_cpu > 0.85. Don't include a FROM clause.

recovery union oneOf

When an alert recovers. Required when kind is alert. Not allowed when kind is signal.

One of: (determined by strategy)
strategy: no_breach

Recovers the alert when its group no longer appears in the breach results.

strategy enum required
Values: no_breach
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.

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.

pending object
count integer · min: 0 · max: 1000

Consecutive matches the alert spends in pending before it becomes active on the next match. For example, 2 opens it on the third consecutive match. Set to 0 to open it on the first match.

operator enum

When both count and timeframe are set, and requires both and or requires either. Allowed only when both fields are present.

Values: and or
timeframe string · max length: 32

Duration the condition must hold, for example 5m. Combine with count using operator.

recovering object
count integer · min: 0 · max: 1000

Consecutive recoveries the alert spends in recovering before it becomes inactive on the next recovery. For example, 2 closes it on the third consecutive recovery. Set to 0 to close it on the first recovery.

operator enum

When both count and timeframe are set, and requires both and or requires either. Allowed only when both fields are present.

Values: and or
timeframe string · max length: 32

Duration the condition must hold, for example 5m. Combine with count using operator.

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.

profile_uid string required nullable

User profile ID of the actor, or null when it cannot be resolved.

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
code string required

Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.

details map string to object

Optional structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.

error string required

A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.

message string required

A readable explanation of the error. The wording can change without notice. Do not parse this field.

Indicates the request was not authenticated.

application/json
code string required

Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.

details map string to object

Optional structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.

error string required

A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.

message string required

A readable explanation of the error. The wording can change without notice. Do not parse this field.

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

application/json
code string required

Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.

details map string to object

Optional structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.

error string required

A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.

message string required

A readable explanation of the error. The wording can change without notice. Do not parse this field.

Indicates an unexpected server-side error.

application/json
code string required

Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.

details map string to object

Optional structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.

error string required

A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.

message string required

A readable explanation of the error. The wording can change without notice. Do not parse this field.

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

application/json
code string required

Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.

details map string to object

Optional structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.

error string required

A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.

message string required

A readable explanation of the error. The wording can change without notice. Do not parse this field.

Base URL
https://{kibana_url}