Update a rule

Base URL: https://{kibana_url}

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

Required authorization

Authentication

Api key

Authorization: <value>

These APIs use key-based authentication. You must create an API key and use the encoded value in the request header. For example: Authorization: ApiKey base64AccessApiKey

Basic

Authorization: Basic <credentials>

Path parameters

Header parameters

Request body

artifacts object[] · max items: 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 object
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 oneOf: 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 length: 1 · max length: 128: Document field used as the event time when applying the lookback window. If omitted, the existing value is kept.
version string · min length: 1 · max length: 256: The current version of the rule, used for optimistic concurrency control.

Responses

Returns the updated rule.

application/json

artifacts object[] · 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.
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 object: 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 object 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 oneOf 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 object 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 length: 1 · max length: 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

Base URL: https://{kibana_url}

Examples

Request Console 1 / 2 languages

Console Kibana Dev Tools

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

Generated from the API spec

curl Shell

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

Generated from the API spec

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

Required authorization

Authentication

Path parameters

Header parameters

Request body { }

Responses

Request body