Update a rule

Server: https://{kibana_url}

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

Api key auth Basic auth

[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 nullable: 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 {}
metadata object
no_data_strategy enum: How the rule behaves when it finds no data for a group. If omitted, the existing value is kept. Set to null to clear it (those runs are then 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: Detection query configuration.; One of: (determined by format)
recovery_strategy enum: The condition that marks an alert recovered. If omitted, the existing value is kept. Set to null to clear it (recovery is then disabled). Set to no_breach to recover when the breach query stops returning matches. Set to query only when you also provide query.recovery. With none, the alert stays active, even after the breach query stops returning matches. state_transition.recovering_count and recovering_timeframe require an explicit recovery_strategy other than none.; Values: no_breach query none
schedule object nullable
state_transition union anyOf: Any of:
time_field string · min: 1 · max: 128: Document field used as the event time when applying the lookback window. If omitted, the existing value is kept.
version string · min: 1 · max: 256: The current version of the rule, used for optimistic concurrency control.

Responses

Returns the updated 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 a rule with the given ID does not exist.

application/json

Indicates the rule was concurrently updated by another caller.

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

PATCH /api/alerting/v2/rules/{id}
{
  "metadata": {
    "description": "Updated description.",
    "name": "Host CPU high (updated)"
  },
  "version": "WzAsMV0="
}

curl Shell

curl -X PATCH "https://{kibana_url}/api/alerting/v2/rules/{id}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
  "metadata": {
    "description": "Updated description.",
    "name": "Host CPU high (updated)"
  },
  "version": "WzAsMV0="
}'

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": "Updated description.",
    "name": "Host CPU high (updated)",
    "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": {
      "unknownField": [
        "Unrecognized key"
      ]
    }
  },
  "error": "Bad Request",
  "message": "Unrecognized key(s) in object: \u0027unknownField\u0027"
}

{
  "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_NOT_FOUND",
  "details": {
    "rule_id": "rule-1"
  },
  "error": "Not Found",
  "message": "Rule with id \u0022rule-1\u0022 not found"
}

{
  "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 , metadata , no_data_strategy , query , recovery_strategy , schedule , state_transition , time_field , version , }

Responses

Request