--- title: "Create a rule" method: POST path: "/api/alerting/v2/rules" tags: ["alerting-v2"] --- # Create a rule `POST /api/alerting/v2/rules` **Spaces method and path for this operation:**
post /s/{space_id}/api/alerting/v2/rules
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information. 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/.

[Required authorization] Route required privileges: manage_alerting-v2-rules. ## Headers - `kbn-xsrf` string, required ## Request body - KibanaHTTPAPIsAlertingNewRule - `artifacts` KibanaHTTPAPIsAlertingRuleArtifact[] — Artifacts attached to the rule, each shaped as `{ id, type, data }`. `data` carries type-specific fields: a `runbook` artifact requires `data.content` holding markdown, and a `dashboard` artifact requires `data.dashboardId` holding a dashboard saved object id. Artifacts of any other type may carry whatever fields they need in `data`. - `data` object, required — Structured artifact data. - `id` string, required — Artifact identifier. - `type` string, required — Artifact type. - `grouping` KibanaHTTPAPIsAlertingRuleGrouping — Grouping configuration. - `fields` string[], required — Fields to group alerts by, e.g. ["host.name", "service.name"]. Should match ES|QL GROUP BY fields. - `kind` union, required — The kind of the rule. - 'alert' — Default. Tracks each problem as an alert episode across state changes — lifecycle, recovery detection, and notification dispatch via workflows. Use when the user wants to be notified, needs lifecycle tracking, or wants recovery detection. - 'signal' — Records each match as a queryable event with no alerts, lifecycle tracking, or notifications — just data. Use for logging or detection without automated action. - `metadata` KibanaHTTPAPIsAlertingRuleMetadata, required — Rule metadata. - `builder_type` string — Identifies the rule builder that authored this rule (e.g. "threshold"). Absent for rules authored directly in ES|QL. - `description` string — Human-readable description of the rule. - `name` string, required — Rule name (must be unique within the space). - `owner` string — Owner of the rule. - `tags` string[] — Tags for categorization, e.g. ["production", "infra"]. - `no_data_strategy` union — How to handle no-data situations. "last_known_status" holds the last known status; "recover" forces recovery; "none" disables no-data detection. "emit" is not currently accepted by the create/update API. Standalone-format rules must provide a `no_data` query block when this is not "none"; composed-format rules use `base` as the data-presence query. - 'last_known_status' — Holds the last known episode status when no data is present. - 'emit' — Emits a `no_data` alert event when no_data query returns no rows for the group. "emit" is not currently accepted by the create/update API. - 'recover' — Forces recovery when no data is present. - 'none' — No-data situations are ignored (default). - `query` union, required — Detection query configuration. - KibanaHTTPAPIsAlertingComposedRuleQuery — Composed query: a shared base with appendable breach and recovery segments. - `base` string, required — Base ES|QL query. Time filters are applied automatically via the lookback window. - `breach` object, required — Breach detection configuration (required). - `segment` string, required — Appendable ES|QL segment for breach detection (required). - `format` 'composed', required - `recovery` object — Recovery query segment. Required when recovery_strategy is "query". - `segment` string, required — Appendable ES|QL segment for recovery detection. - KibanaHTTPAPIsAlertingStandaloneRuleQuery — Standalone queries: independent full queries for breach, recovery, and no_data. - `breach` object, required — Breach detection configuration (required). - `query` string, required — Full ES|QL query for breach detection (required). - `format` 'standalone', required - `no_data` object — No-data detection query. Required when no_data_strategy is not "none". - `query` string, required — Full ES|QL query that detects presence of data. - `recovery` object — Recovery query. Required when recovery_strategy is "query". - `query` string, required — Full ES|QL query for recovery detection. - `recovery_strategy` union — How recovery is detected. "no_breach" recovers groups that stop breaching; "query" uses a custom recovery query; "none" disables recovery. - 'no_breach' — recovers groups that stop breaching (default). - 'query' — uses a custom recovery query to detect recovery. - 'none' — disables recovery entirely. - `schedule` KibanaHTTPAPIsAlertingRuleSchedule, required — Execution schedule configuration. - `every` string, required — Execution interval, e.g. 1m, 5m, 1h. - `lookback` string — Lookback window for the query, e.g. 5m, 1h. Can also be expressed in ES|QL. - `state_transition` object, nullable — Episode state transition thresholds (alert-only). - `pending_count` integer — Consecutive breaches before transitioning to active. - `pending_operator` 'AND' | 'OR' — How to combine count and timeframe for pending. - `pending_timeframe` string — Time window for pending evaluation, e.g. 5m, 15m. - `recovering_count` integer — Consecutive recoveries before transitioning to inactive. - `recovering_operator` 'AND' | 'OR' — How to combine count and timeframe for recovering. - `recovering_timeframe` string — Time window for recovering evaluation, e.g. 5m, 15m. - `time_field` string — Time field used for the lookback window range filter. ## Response `201` Returns the newly created rule. - KibanaHTTPAPIsAlertingRuleResponse - `artifacts` KibanaHTTPAPIsAlertingRuleArtifact[] — Artifacts attached to the rule, each shaped as `{ id, type, data }`. `data` carries type-specific fields: a `runbook` artifact requires `data.content` holding markdown, and a `dashboard` artifact requires `data.dashboardId` holding a dashboard saved object id. Artifacts of any other type may carry whatever fields they need in `data`. - `data` object, required — Structured artifact data. - `id` string, required — Artifact identifier. - `type` string, required — Artifact type. - `created_at` string, required — ISO timestamp when the rule was created. - `created_by` string, nullable, required — User who created the rule. - `enabled` boolean, required — Whether the rule is enabled. - `grouping` KibanaHTTPAPIsAlertingRuleGrouping — Grouping configuration. - `fields` string[], 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` union, required — The kind of the rule. - 'alert' — Default. Tracks each problem as an alert episode across state changes — lifecycle, recovery detection, and notification dispatch via workflows. Use when the user wants to be notified, needs lifecycle tracking, or wants recovery detection. - 'signal' — Records each match as a queryable event with no alerts, lifecycle tracking, or notifications — just data. Use for logging or detection without automated action. - `metadata` KibanaHTTPAPIsAlertingRuleResponseMetadata, required - `builder_type` string — Identifies the rule builder that authored this rule (e.g. "threshold"). Absent for rules authored directly in ES|QL. - `description` string — Human-readable description of the rule. - `name` string, required — Rule name (must be unique within the space). - `owner` string — Owner of the rule. - `tags` string[] — Tags for categorization, e.g. ["production", "infra"]. - `version` integer, 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` union — How to handle no-data situations. "last_known_status" holds the last known status; "recover" forces recovery; "none" disables no-data detection. "emit" is not currently accepted by the create/update API. Standalone-format rules must provide a `no_data` query block when this is not "none"; composed-format rules use `base` as the data-presence query. - 'last_known_status' — Holds the last known episode status when no data is present. - 'emit' — Emits a `no_data` alert event when no_data query returns no rows for the group. "emit" is not currently accepted by the create/update API. - 'recover' — Forces recovery when no data is present. - 'none' — No-data situations are ignored (default). - `query` union, required — Detection query configuration. - KibanaHTTPAPIsAlertingComposedRuleQuery — Composed query: a shared base with appendable breach and recovery segments. - `base` string, required — Base ES|QL query. Time filters are applied automatically via the lookback window. - `breach` object, required — Breach detection configuration (required). - `segment` string, required — Appendable ES|QL segment for breach detection (required). - `format` 'composed', required - `recovery` object — Recovery query segment. Required when recovery_strategy is "query". - `segment` string, required — Appendable ES|QL segment for recovery detection. - KibanaHTTPAPIsAlertingStandaloneRuleQuery — Standalone queries: independent full queries for breach, recovery, and no_data. - `breach` object, required — Breach detection configuration (required). - `query` string, required — Full ES|QL query for breach detection (required). - `format` 'standalone', required - `no_data` object — No-data detection query. Required when no_data_strategy is not "none". - `query` string, required — Full ES|QL query that detects presence of data. - `recovery` object — Recovery query. Required when recovery_strategy is "query". - `query` string, required — Full ES|QL query for recovery detection. - `recovery_strategy` union — How recovery is detected. "no_breach" recovers groups that stop breaching; "query" uses a custom recovery query; "none" disables recovery. - 'no_breach' — recovers groups that stop breaching (default). - 'query' — uses a custom recovery query to detect recovery. - 'none' — disables recovery entirely. - `schedule` KibanaHTTPAPIsAlertingRuleSchedule, required — Execution schedule configuration. - `every` string, required — Execution interval, e.g. 1m, 5m, 1h. - `lookback` string — Lookback window for the query, e.g. 5m, 1h. Can also be expressed in ES|QL. - `state_transition` object, nullable — Episode state transition thresholds (alert-only). - `pending_count` integer — Consecutive breaches before transitioning to active. - `pending_operator` 'AND' | 'OR' — How to combine count and timeframe for pending. - `pending_timeframe` string — Time window for pending evaluation, e.g. 5m, 15m. - `recovering_count` integer — Consecutive recoveries before transitioning to inactive. - `recovering_operator` 'AND' | 'OR' — How to combine count and timeframe for recovering. - `recovering_timeframe` string — Time window for recovering evaluation, e.g. 5m, 15m. - `time_field` string — Time field used for the lookback window range filter. - `updated_at` string, required — ISO timestamp when the rule was last updated. - `updated_by` string, nullable, required — User who last updated the rule. - `version` string — The saved object version token of the rule, used for optimistic concurrency control. ## Other responses - `400` — Indicates an invalid schema or parameters. - `401` — Indicates the request was not authenticated. - `403` — Indicates the user does not have the required privileges to perform the request. - `500` — Indicates an unexpected server-side error. - `503` — Indicates the alerting engine is disabled by the `alerting:v2:enabled` advanced setting. --- [API](https://skmtc.net/elastic/apis/kibana-apis.md) · [All operations](https://skmtc.net/elastic/apis/kibana-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/elastic/kibana-apis/revisions/e9badbb5da99/schema)