Update a rule | Kibana Serverless API documentation

Update a rule Experimental

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

Spaces method and path for this operation:

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.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string 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 alerts 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.

Minimum length is 1, maximum length is 150. Format should match the following pattern: ^[a-zA-Z0-9_-]+$.

application/json

Body

artifacts array[object] | null

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.

At least 1 but not more than 100 elements.
Hide artifacts attributes Show artifacts attributes object
- data object Required
  
  Structured artifact data.
  
  Additional properties are allowed.
- id string Required
  
  Artifact identifier.
  
  Minimum length is 1, maximum length is 150.
- type string Required
  
  Artifact type.
  
  Minimum length is 1, maximum length is 128.
grouping object

Grouping configuration.

Additional properties are NOT allowed.
Hide grouping attribute Show grouping attribute object
- fields array[string]
  
  Fields to group alerts by, e.g. ["host.name", "service.name"]. Should match ES|QL GROUP BY fields.
  
  At least 1 but not more than 16 elements. Minimum length of each is 1, maximum length of each is 256.
metadata object

Rule metadata.

Additional properties are NOT allowed.
Hide metadata attributes Show metadata attributes object
- builder object | null
  
  Identifies the rule builder that authored this rule (e.g. "threshold"). Absent for rules authored directly in ES|QL; send null on PATCH to clear it.
  
  Additional properties are NOT allowed.
  Hide builder attribute Show builder attribute object | null
  
  type string Required
  
  Rule builder type.
  
  Minimum length is 1, maximum length is 64.
- description string | null
  
  Human-readable description of the rule. Omit to leave it unset; send null on PATCH to clear it. An empty string is rejected.
  
  Minimum length is 1, maximum length is 1024.
- name string
  
  Rule name (must be unique within the space).
  
  Minimum length is 1, maximum length is 256.
- routing_tags array[string] | null
  
  Routing tags that link alerts from this rule to action policies. An action policy applies when its matcher.tags contains at least one of these tags. Only allowed when kind is "alert".
  
  At least 1 but not more than 20 elements. Minimum length of each is 1, maximum length of each is 128.
- tags array[string] | null
  
  Tags for categorization, e.g. ["production", "infra"].
  
  At least 1 but not more than 20 elements. Minimum length of each is 1, maximum length of each is 128.
no_data

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.
Hide no_data attributes Show no_data attributes
- strategy Required Discriminator
- query string
  
  Optional ES|QL query that checks whether a group has data. If omitted, query.base is used, which then has to be a presence query in its own right — so query.breach is required.
  
  Minimum length is 1, maximum length is 10000.
query object

ES|QL query the rule evaluates. base is required. breach is an optional clause appended to it.

Additional properties are NOT allowed.
Hide query attributes Show query attributes object
- base string
  
  ES|QL query that specifies the data to evaluate. Must include a FROM clause. Kibana applies the time filter from schedule.lookback using time_field.
  
  Minimum length is 1, maximum length is 10000.
- breach object
  
  Optional ES|QL clause appended to query.base. If omitted, every row from query.base is a match, and a no_data strategy other than ignore then requires no_data.query.
  
  Additional properties are NOT allowed.
  Hide breach attribute Show breach attribute object
  
  segment string
  
  ES|QL clause appended to query.base, for example WHERE avg_cpu > 0.85. Don't include a FROM clause.
  
  Minimum length is 1, maximum length is 10000.
recovery

When an alert recovers. Required when kind is alert. Not allowed when kind is signal.
Hide recovery attributes Show recovery attributes
- strategy Required Discriminator
- segment string Required
  
  ES|QL clause appended to query.base, for example WHERE avg_cpu < 0.60. Don't include a FROM clause.
  
  Minimum length is 1, maximum length is 10000.
- query string Required
  
  Independent ES|QL query, including its own FROM clause. A matching group recovers the alert.
  
  Minimum length is 1, maximum length is 10000.
schedule object

Execution schedule configuration.

Additional properties are NOT allowed.
Hide schedule attributes Show schedule attributes object
- every string
  
  Execution interval, e.g. 1m, 5m, 1h.
  
  Maximum length is 32.
- lookback string | null
  
  Lookback window for the query, e.g. 5m, 1h. Can also be expressed in ES|QL.
  
  Maximum length is 32.
state_transition object

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.

Additional properties are NOT allowed.
Hide state_transition attributes Show state_transition attributes object
- pending object
  
  Delay before a match opens an alert.
  
  Additional properties are NOT allowed.
  Hide pending attributes Show pending attributes object
  
  count integer | null
  
  Consecutive matches the alert spends in pending before it becomes active on the next match. For example, 2 opens it on the third consecutive match. Set to 0 to open it on the first match.
  
  Minimum value is 0, maximum value is 1000.
  
  operator string | null
  
  When both count and timeframe are set, and requires both and or requires either. Allowed only when both fields are present.
  
  Values are and or or.
  
  timeframe string | null
  
  Duration the condition must hold, for example 5m. Combine with count using operator.
  
  Maximum length is 32.
- recovering object
  
  Delay before a recovered match closes the alert. Has no effect when recovery.strategy is manual.
  
  Additional properties are NOT allowed.
  Hide recovering attributes Show recovering attributes object
  
  count integer | null
  
  Consecutive recoveries the alert spends in recovering before it becomes inactive on the next recovery. For example, 2 closes it on the third consecutive recovery. Set to 0 to close it on the first recovery.
  
  Minimum value is 0, maximum value is 1000.
  
  operator string | null
  
  When both count and timeframe are set, and requires both and or requires either. Allowed only when both fields are present.
  
  Values are and or or.
  
  timeframe string | null
  
  Duration the condition must hold, for example 5m. Combine with count using operator.
  
  Maximum length is 32.
time_field string

Document field Kibana uses with schedule.lookback to time-filter query.base.

Minimum length is 1, maximum length is 256.

Responses

200 application/json

Returns the updated rule.
Hide response attributes Show response attributes object
- artifacts array[object]
  
  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.
  
  At least 1 but not more than 100 elements.
  
  Hide artifacts attributes Show artifacts attributes object
  
  data object Required
  
  Structured artifact data.
  
  Additional properties are allowed.
  
  id string Required
  
  Artifact identifier.
  
  Minimum length is 1, maximum length is 150.
  
  type string Required
  
  Artifact type.
  
  Minimum length is 1, maximum length is 128.
- created_at string(date-time) Required
  
  ISO timestamp when the rule was created.
- created_by object Required
  
  Actor who created the rule.
  
  Additional properties are NOT allowed.
  
  Hide created_by attribute Show created_by attribute object
  
  profile_uid string | null Required
  
  User profile ID of the actor, or null when it cannot be resolved.
- enabled boolean Required
  
  Whether the rule is enabled.
- grouping object
  
  Grouping configuration.
  
  Additional properties are NOT allowed.
  
  Hide grouping attribute Show grouping attribute object
  
  fields array[string] Required
  
  Fields to group alerts by, e.g. ["host.name", "service.name"]. Should match ES|QL GROUP BY fields.
  
  At least 1 but not more than 16 elements. Minimum length of each is 1, maximum length of each is 256.
- id string Required
  
  Unique rule identifier.
- kind string Required
  Whether the rule creates alerts (alert) or only stores matching events (signal).
  
  Any of:
  string-1 string string-2 string
  
  Creates an alert for each matching group and tracks it until it recovers. Use this when you want to detect a problem and notify or automate a response.
  
  Value is alert.
  
  Stores each match as a rule event you can query. Alerts are not created and notifications are not sent.
  
  Value is signal.
- metadata object Required
  
  Rule metadata.
  
  Additional properties are NOT allowed.
  
  Hide metadata attributes Show metadata attributes object
  
  builder object
  
  Identifies the rule builder that authored this rule (e.g. "threshold"). Absent for rules authored directly in ES|QL; send null on PATCH to clear it.
  
  Additional properties are NOT allowed.
  
  Hide builder attribute Show builder attribute object
  
  type string Required
  
  Rule builder type.
  
  Minimum length is 1, maximum length is 64.
  
  description string
  
  Human-readable description of the rule. Omit to leave it unset; send null on PATCH to clear it. An empty string is rejected.
  
  Minimum length is 1, maximum length is 1024.
  
  name string Required
  
  Rule name (must be unique within the space).
  
  Minimum length is 1, maximum length is 256.
  
  routing_tags array[string]
  
  Routing tags that link alerts from this rule to action policies. An action policy applies when its matcher.tags contains at least one of these tags. Only allowed when kind is "alert".
  
  At least 1 but not more than 20 elements. Minimum length of each is 1, maximum length of each is 128.
  
  tags array[string]
  
  Tags for categorization, e.g. ["production", "infra"].
  
  At least 1 but not more than 20 elements. Minimum length of each is 1, maximum length of each is 128.
  
  template object
  
  The rule template this rule was created from.
  
  Additional properties are NOT allowed.
  
  Hide template attribute Show template attribute object
  
  id string Required
  
  Id of the rule template.
- 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.
  
  One of:
  ignore object keep_last object resolve object alert object
  
  Holds the alert's current status when the rule finds no data.
  
  Hide attributes Show attributes
  
  query string
  
  Optional ES|QL query that checks whether a group has data. If omitted, query.base is used, which then has to be a presence query in its own right — so query.breach is required.
  
  Minimum length is 1, maximum length is 10000.
  
  strategy string Required Discriminator
  
  Value is keep_last.
  
  Closes the alert the first time the rule finds no data for a group.
  
  Hide attributes Show attributes
  
  query string
  
  Optional ES|QL query that checks whether a group has data. If omitted, query.base is used, which then has to be a presence query in its own right — so query.breach is required.
  
  Minimum length is 1, maximum length is 10000.
  
  strategy string Required Discriminator
  
  Value is resolve.
  
  Marks an existing alert active when the rule finds no data. It never opens an alert for a group that has not breached. Not accepted when creating or updating rules.
  
  Hide attributes Show attributes
  
  query string
  
  Optional ES|QL query that checks whether a group has data. If omitted, query.base is used, which then has to be a presence query in its own right — so query.breach is required.
  
  Minimum length is 1, maximum length is 10000.
  
  strategy string Required Discriminator
  
  Value is alert.
- query object Required
  
  ES|QL query the rule evaluates. base is required. breach is an optional clause appended to it.
  
  Additional properties are NOT allowed.
  
  Hide query attributes Show query attributes object
  
  base string Required
  
  ES|QL query that specifies the data to evaluate. Must include a FROM clause. Kibana applies the time filter from schedule.lookback using time_field.
  
  Minimum length is 1, maximum length is 10000.
  
  breach object
  
  Optional ES|QL clause appended to query.base. If omitted, every row from query.base is a match, and a no_data strategy other than ignore then requires no_data.query.
  
  Additional properties are NOT allowed.
  
  Hide breach attribute Show breach attribute object
  
  segment string Required
  
  ES|QL clause appended to query.base, for example WHERE avg_cpu > 0.85. Don't include a FROM clause.
  
  Minimum length is 1, maximum length is 10000.
- recovery object
  When an alert recovers. Required when kind is alert. Not allowed when kind is signal.
  
  One of:
  no_breach object condition object query object manual object
  
  Recovers the alert when query.base plus segment returns the group. Requires query.breach.
  
  Hide attributes Show attributes
  
  segment string Required
  
  ES|QL clause appended to query.base, for example WHERE avg_cpu < 0.60. Don't include a FROM clause.
  
  Minimum length is 1, maximum length is 10000.
  
  strategy string Required Discriminator
  
  Value is condition.
  
  Recovers the alert when this separate query returns the group.
  
  Hide attributes Show attributes
  
  query string Required
  
  Independent ES|QL query, including its own FROM clause. A matching group recovers the alert.
  
  Minimum length is 1, maximum length is 10000.
  
  strategy string Required Discriminator
  
  Value is query.
- schedule object Required
  
  Execution schedule configuration.
  
  Additional properties are NOT allowed.
  
  Hide schedule attributes Show schedule attributes object
  
  every string Required
  
  Execution interval, e.g. 1m, 5m, 1h.
  
  Maximum length is 32.
  
  lookback string
  
  Lookback window for the query, e.g. 5m, 1h. Can also be expressed in ES|QL.
  
  Maximum length is 32.
- state_transition object
  
  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.
  
  Additional properties are NOT allowed.
  
  Hide state_transition attributes Show state_transition attributes object
  
  pending object
  
  Delay before a match opens an alert.
  
  Additional properties are NOT allowed.
  
  Hide pending attributes Show pending attributes object
  
  count integer
  
  Consecutive matches the alert spends in pending before it becomes active on the next match. For example, 2 opens it on the third consecutive match. Set to 0 to open it on the first match.
  
  Minimum value is 0, maximum value is 1000.
  
  operator string
  
  When both count and timeframe are set, and requires both and or requires either. Allowed only when both fields are present.
  
  Values are and or or.
  
  timeframe string
  
  Duration the condition must hold, for example 5m. Combine with count using operator.
  
  Maximum length is 32.
  
  recovering object
  
  Delay before a recovered match closes the alert. Has no effect when recovery.strategy is manual.
  
  Additional properties are NOT allowed.
  
  Hide recovering attributes Show recovering attributes object
  
  count integer
  
  Consecutive recoveries the alert spends in recovering before it becomes inactive on the next recovery. For example, 2 closes it on the third consecutive recovery. Set to 0 to close it on the first recovery.
  
  Minimum value is 0, maximum value is 1000.
  
  operator string
  
  When both count and timeframe are set, and requires both and or requires either. Allowed only when both fields are present.
  
  Values are and or or.
  
  timeframe string
  
  Duration the condition must hold, for example 5m. Combine with count using operator.
  
  Maximum length is 32.
- time_field string
  
  Document field Kibana uses with schedule.lookback to time-filter query.base.
  
  Minimum length is 1, maximum length is 256. Default value is @timestamp.
- updated_at string(date-time) Required
  
  ISO timestamp when the rule was last updated.
- updated_by object Required
  
  Actor who last updated the rule.
  
  Additional properties are NOT allowed.
  
  Hide updated_by attribute Show updated_by attribute object
  
  profile_uid string | null Required
  
  User profile ID of the actor, or null when it cannot be resolved.
- version integer Required
  
  Monotonically increasing integer number representing a rule configuration version, incremented on every change. Used on generated rule events as rule.version.
  
  Minimum value is 1, maximum value is 9007199254740991.
400 application/json

Indicates an invalid schema or parameters.
Hide response attributes Show response attributes object
- code string Required
  
  Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
- details object
  
  Optional extra information about the error, for example field validation issues or the rule_id when that ID already exists.
  
  Additional properties are allowed.
- error string Required
  
  A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.
- message string Required
  
  A readable explanation of the error. The wording can change without notice. Do not parse this field.
401 application/json

Indicates the request was not authenticated.
Hide response attributes Show response attributes object
- code string Required
  
  Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
- details object
  
  Optional extra information about the error, for example field validation issues or the rule_id when that ID already exists.
  
  Additional properties are allowed.
- error string Required
  
  A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.
- message string Required
  
  A readable explanation of the error. The wording can change without notice. Do not parse this field.
403 application/json

Indicates the user does not have the required privileges to perform the request.
Hide response attributes Show response attributes object
- code string Required
  
  Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
- details object
  
  Optional extra information about the error, for example field validation issues or the rule_id when that ID already exists.
  
  Additional properties are allowed.
- error string Required
  
  A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.
- message string Required
  
  A readable explanation of the error. The wording can change without notice. Do not parse this field.
404 application/json

Indicates a rule with the given ID does not exist.
Hide response attributes Show response attributes object
- code string Required
  
  Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
- details object
  
  Optional extra information about the error, for example field validation issues or the rule_id when that ID already exists.
  
  Additional properties are allowed.
- error string Required
  
  A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.
- message string Required
  
  A readable explanation of the error. The wording can change without notice. Do not parse this field.
409 application/json

Indicates the rule was concurrently updated by another caller.
Hide response attributes Show response attributes object
- code string Required
  
  Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
- details object
  
  Optional extra information about the error, for example field validation issues or the rule_id when that ID already exists.
  
  Additional properties are allowed.
- error string Required
  
  A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.
- message string Required
  
  A readable explanation of the error. The wording can change without notice. Do not parse this field.
500 application/json

Indicates an unexpected server-side error.
Hide response attributes Show response attributes object
- code string Required
  
  Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
- details object
  
  Optional extra information about the error, for example field validation issues or the rule_id when that ID already exists.
  
  Additional properties are allowed.
- error string Required
  
  A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.
- message string Required
  
  A readable explanation of the error. The wording can change without notice. Do not parse this field.
503 application/json

Indicates the alerting engine is disabled by the alerting:v2:enabled advanced setting.
Hide response attributes Show response attributes object
- code string Required
  
  Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
- details object
  
  Optional extra information about the error, for example field validation issues or the rule_id when that ID already exists.
  
  Additional properties are allowed.
- error string Required
  
  A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.
- message string Required
  
  A readable explanation of the error. The wording can change without notice. Do not parse this field.

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

curl \
 --request PATCH 'https://<KIBANA_URL>/api/alerting/v2/rules/{id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{
  "metadata": {
    "description": "Updated description.",
    "name": "Host CPU high (updated)",
    "tags": null
  }
}'

Request example

{
  "metadata": {
    "description": "Updated description.",
    "name": "Host CPU high (updated)",
    "tags": null
  }
}

Response examples (200)

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

Response examples (400)

{
  "code": "BAD_REQUEST",
  "details": {
    "errors": {
      "unknownField": [
        "Unrecognized key"
      ]
    }
  },
  "error": "Bad Request",
  "message": "Unrecognized key(s) in object: 'unknownField'"
}

Response examples (401)

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

Response examples (403)

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

Response examples (404)

{
  "code": "RULE_NOT_FOUND",
  "details": {
    "rule_id": "rule-1"
  },
  "error": "Not Found",
  "message": "Rule with id \"rule-1\" not found"
}

Response examples (409)

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

Response examples (500)

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

Response examples (503)

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