Update a rule

Server: https://{kibana_url}

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

Refer to Spaces for more information.

Apply a partial update. A field you omit keeps its stored value, and that applies at every level: send {"metadata": {"name": "Disk pressure"}} to change one leaf while leaving its siblings alone. Send null to clear a field, again at any level: {"metadata": {"description": null}} clears a single leaf, while {"grouping": null} clears a whole object. Lists and variant objects are replaced as a unit rather than merged, since a partly-sent variant could never be valid. The merged result is validated as a whole, so a patch that would leave the resource invalid is rejected with a 400 and nothing is stored.

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

Path Parameters

id string · min: 1 · max: 150 · pattern: ^[a-zA-Z0-9_-]+$ required: The identifier for the rule. Chosen at creation and permanent — it cannot be changed afterwards. Re-using the id of a deleted resource is allowed but discouraged: execution history, change history, and alert episodes recorded under that id are retained and are attributed to the new resource. Ids appear in URLs and logs, so keep them free of sensitive data.

Request

artifacts [] object · min: 1 · 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. An empty array is rejected: omit artifacts on create, or send null on PATCH to clear.
grouping {}: Grouping configuration.
metadata {}: Rule metadata.
no_data object: 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.
query {}: ES|QL query the rule evaluates. base is required. breach is an optional clause appended to it.
recovery object: When an alert recovers. Required when kind is alert. Not allowed when kind is signal.
schedule {}: Execution schedule configuration.
state_transition {}: 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.
time_field string · min: 1 · max: 256: Document field Kibana uses with schedule.lookback to time-filter query.base.

Responses

Returns the updated rule.

application/json

artifacts [] object · min: 1 · 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. An empty array is rejected: omit artifacts on create, or send null on PATCH to clear.
created_at string · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: ISO timestamp when the rule was created.
created_by {} required: Actor 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: Rule metadata.
no_data union: 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)
query {} required: ES|QL query the rule evaluates. base is required. breach is an optional clause appended to it.
recovery union: When an alert recovers. Required when kind is alert. Not allowed when kind is signal.; One of: (determined by strategy)
schedule {} required: Execution schedule configuration.
state_transition {}: 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.
time_field string · min: 1 · max: 256 · default: @timestamp: Document field Kibana uses with schedule.lookback to time-filter query.base.
updated_at string · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: ISO timestamp when the rule was last updated.
updated_by {} required: Actor who last updated the rule.
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

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)",
    "tags": "null"
  }
}

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)",
    "tags": "null"
  }
}'

Response

{
  "created_at": "2026-01-15T12:00:00.000Z",
  "created_by": {
    "profile_uid": "u_elastic_0"
  },
  "enabled": true,
  "grouping": {
    "fields": [
      "host.name"
    ]
  },
  "id": "rule-1",
  "kind": "alert",
  "metadata": {
    "description": "Updated description.",
    "name": "Host CPU high (updated)",
    "routing_tags": [
      "sre-oncall"
    ],
    "tags": [
      "production",
      "infra"
    ]
  },
  "no_data": {
    "strategy": "keep_last"
  },
  "query": {
    "base": "FROM metrics-* | STATS avg_cpu = AVG(host.cpu.usage) BY host.name",
    "breach": {
      "segment": "WHERE avg_cpu \u003E 0.9"
    }
  },
  "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": {
    "profile_uid": "u_elastic_0"
  },
  "version": 1
}

{
  "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 , query , recovery , schedule , state_transition , time_field , }

Responses

Request