Create or replace a rule

Server: https://{kibana_url}

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

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

[Required authorization] Route required privileges: manage_alerting-v2-rules.

Path Parameters

id string · min: 1 · max: 150 required: The identifier for the rule.

Request

artifacts [] object · max: 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.
grouping {}: Grouping configuration.
kind enum required: Whether the rule creates alerts (alert) or only stores matching events (signal).; Values: alert signal
metadata {} required: Rule metadata.
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 required: Detection query configuration.; One of: (determined by format)
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 {} required: Execution schedule configuration.
state_transition object nullable: Consecutive-match or time requirements before an alert becomes active or inactive. Applies only when kind is alert.
time_field string · min: 1 · max: 128 · default: @timestamp: Document field used as the event time when applying the lookback window. Defaults to @timestamp.

Responses

Returns the replaced rule.

application/json

artifacts [] object · max: 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.
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.
grouping {}: 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 {} required
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 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 {} required: Execution schedule configuration.
state_transition object nullable: Consecutive-match or time requirements before an alert becomes active or inactive. Applies only when kind is alert.
time_field string · min: 1 · max: 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.

Returns the newly created rule.

application/json

artifacts [] object · max: 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.
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.
grouping {}: 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 {} required
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 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 {} required: Execution schedule configuration.
state_transition object nullable: Consecutive-match or time requirements before an alert becomes active or inactive. Applies only when kind is alert.
time_field string · min: 1 · max: 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.

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

Examples

Request Console 1 / 2 languages

Console Kibana Dev Tools

PUT /api/alerting/v2/rules/{id}
{
  "grouping": {
    "fields": [
      "host.name"
    ]
  },
  "kind": "alert",
  "metadata": {
    "description": "Alerts when average CPU usage exceeds a threshold.",
    "name": "Host CPU high",
    "tags": [
      "production",
      "infra"
    ]
  },
  "query": {
    "breach": {
      "query": "FROM metrics-* | WHERE host.cpu.usage \u003E 0.9 | STATS avg_cpu = AVG(host.cpu.usage) BY host.name"
    },
    "format": "standalone"
  },
  "recovery_strategy": "no_breach",
  "schedule": {
    "every": "1m",
    "lookback": "5m"
  },
  "state_transition": {
    "pending_count": 1,
    "recovering_count": 1
  },
  "time_field": "@timestamp"
}

curl Shell

curl -X PUT "https://{kibana_url}/api/alerting/v2/rules/{id}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
  "grouping": {
    "fields": [
      "host.name"
    ]
  },
  "kind": "alert",
  "metadata": {
    "description": "Alerts when average CPU usage exceeds a threshold.",
    "name": "Host CPU high",
    "tags": [
      "production",
      "infra"
    ]
  },
  "query": {
    "breach": {
      "query": "FROM metrics-* | WHERE host.cpu.usage \u003E 0.9 | STATS avg_cpu = AVG(host.cpu.usage) BY host.name"
    },
    "format": "standalone"
  },
  "recovery_strategy": "no_breach",
  "schedule": {
    "every": "1m",
    "lookback": "5m"
  },
  "state_transition": {
    "pending_count": 1,
    "recovering_count": 1
  },
  "time_field": "@timestamp"
}'

Response

{
  "created_at": "2026-01-15T12:00:00.000Z",
  "created_by": "elastic",
  "enabled": true,
  "grouping": {
    "fields": [
      "host.name"
    ]
  },
  "id": "rule-1",
  "kind": "alert",
  "metadata": {
    "description": "Alerts when average CPU usage exceeds a threshold.",
    "name": "Host CPU high",
    "tags": [
      "production",
      "infra"
    ],
    "version": 1
  },
  "query": {
    "breach": {
      "query": "FROM metrics-* | WHERE host.cpu.usage \u003E 0.9 | STATS avg_cpu = AVG(host.cpu.usage) BY host.name"
    },
    "format": "standalone"
  },
  "recovery_strategy": "no_breach",
  "schedule": {
    "every": "1m",
    "lookback": "5m"
  },
  "state_transition": {
    "pending_count": 1,
    "recovering_count": 1
  },
  "time_field": "@timestamp",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "updated_by": "elastic",
  "version": "WzAsMV0="
}

{
  "created_at": "2026-01-15T12:00:00.000Z",
  "created_by": "elastic",
  "enabled": true,
  "grouping": {
    "fields": [
      "host.name"
    ]
  },
  "id": "rule-1",
  "kind": "alert",
  "metadata": {
    "description": "Alerts when average CPU usage exceeds a threshold.",
    "name": "Host CPU high",
    "tags": [
      "production",
      "infra"
    ],
    "version": 1
  },
  "query": {
    "breach": {
      "query": "FROM metrics-* | WHERE host.cpu.usage \u003E 0.9 | STATS avg_cpu = AVG(host.cpu.usage) BY host.name"
    },
    "format": "standalone"
  },
  "recovery_strategy": "no_breach",
  "schedule": {
    "every": "1m",
    "lookback": "5m"
  },
  "state_transition": {
    "pending_count": 1,
    "recovering_count": 1
  },
  "time_field": "@timestamp",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "updated_by": "elastic",
  "version": "WzAsMV0="
}

{
  "code": "BAD_REQUEST",
  "details": {
    "errors": {
      "metadata": [
        "Required"
      ]
    }
  },
  "error": "Bad Request",
  "message": "metadata: Required"
}

{
  "code": "UNAUTHORIZED",
  "error": "Unauthorized",
  "message": "Authentication required to access this API."
}

{
  "code": "FORBIDDEN",
  "error": "Forbidden",
  "message": "The current user does not have the required privileges for this request."
}

{
  "code": "RULE_VERSION_CONFLICT",
  "details": {
    "rule_id": "rule-1"
  },
  "error": "Conflict",
  "message": "Rule with id \u0022rule-1\u0022 has already been updated by another user"
}

{
  "code": "INTERNAL_SERVER_ERROR",
  "error": "Internal Server Error",
  "message": "An unexpected error occurred."
}

{
  "code": "ALERTING_DISABLED",
  "error": "Service Unavailable",
  "message": "Alerting is disabled."
}

Path Parameters

Request { artifacts , grouping , kind , metadata , no_data_strategy , query , recovery_strategy , schedule , state_transition , time_field , }

Responses

Request