Partially update an action policy.

Base URL
https://{kibana_url}
  • PATCH /api/alerting/v2/action_policies/{id}
  • PATCH /s/{space_id}/api/alerting/v2/action_policies/{id}
Auth

Apply a partial update. A field you omit keeps its stored value, and that applies at every level: send {"matcher": {"tags": ["prod"]}} to change one leaf while leaving its siblings alone. Send null to clear a field, again at any level: {"matcher": {"expression": null}} clears a single leaf, while {"matcher": 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

Privileges manage_alerting-v2-action-policies and read_alerting-v2-rules

Path parameters

space_id string optional

An identifier for the space. If space_id is not provided in the URL, the default space is used. Refer to Spaces for more information.

id string · min length: 1 · max length: 150 · pattern: ^[a-zA-Z0-9_-]+$ required

The ID of the action policy. Copy it from the response when you create a policy, fetch one policy, or fetch the policy list. 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.

Header parameters

kbn-xsrf string required

A required header to protect against CSRF attacks

Request body

description string · min length: 1 · max length: 1024 nullable

A description of the action policy. Absent when the policy has none; send null on PATCH to clear it.

destinations union oneOf[] · min items: 1 · max items: 10

The list of destinations. At least one is required. Each one can appear at most once.

One of:
{} type: workflow
id string · min length: 1 · max length: 150 required

The workflow identifier.

type enum required

The destination type.

Values: workflow
grouping union oneOf

How matched alerts are batched into notifications. Absent falls back to per_alert; send null on PATCH to clear it. The mode decides the rest of the block, so a PATCH replaces it whole: send the complete mode variant rather than a single field.

One of: (determined by mode)
mode: per_alert

one notification per alert lifecycle (default).

mode enum required
Values: per_alert
matcher object nullable

Selects the alerts this policy applies to. Set tags to match alerts from rules with those routing tags. Set expression to a KQL query, which will be evaluated against each alert.

If you set both tags and expression, an alert must match the tags and the expression for the policy to apply. Omit matcher to keep the stored matcher, or set it to null for a catch-all policy that applies to all alerts. An empty matcher names no leaf and so changes nothing; clearing the last of tags and expression clears the matcher itself, which is also a catch-all.

expression string · min length: 1 · max length: 4096 nullable

A KQL query that's evaluated against each alert. Supported fields are: alert_id, alert_status, group_hash, last_event_timestamp, severity, and your rule's query output columns under data.* (for example, data.host.name). Referencing other fields won't work. Omit matcher.expression to keep the stored expression, or set it to null to clear it and match on tags alone.

tags string[] · min items: 1 · max items: 50 nullable

Routing tags this policy should match. The policy applies to alerts from any rule whose metadata.routing_tags include at least one of these tags. An empty array is not accepted. Omit matcher.tags to keep the stored tags, or set it to null to clear them and match on matcher.expression alone.

name string · min length: 1 · max length: 256

The name of the action policy.

throttle union oneOf

The throttle configuration for notifications. Absent when notifications are not throttled; send null on PATCH to clear it. The strategy decides the rest of the block, so a PATCH replaces it whole: send the complete strategy variant rather than a single field.

One of: (determined by strategy)
strategy: on_status_change

notify only on alert status transitions (default for per_alert).

strategy enum required
Values: on_status_change

Responses

Returns the updated action policy.

application/json
created_at string · format: date-time · max length: 64 required

The ISO datetime when the action policy was created.

created_by object required

The actor who created the action policy.

profile_uid string required nullable

User profile ID of the actor, or null when it cannot be resolved.

description string

A description of the action policy. Omitted when the policy has none.

destinations union oneOf[] required

The list of destinations.

One of:
{} type: workflow
id string · min length: 1 · max length: 150 required

The workflow identifier.

type enum required

The destination type.

Values: workflow
enabled boolean required

Whether the action policy is enabled.

grouping union oneOf
One of: (determined by mode)
mode: per_alert

one notification per alert lifecycle (default).

mode enum required
Values: per_alert
id string required

The unique identifier for the action policy.

matcher object

Selects the alerts this policy applies to. Set tags to match alerts from rules with those routing tags. Set expression to a KQL query, which will be evaluated against each alert.

If you set both tags and expression, an alert must match the tags and the expression for the policy to apply. At least one of tags and expression must be set, so an empty matcher is rejected. Omit matcher entirely for a catch-all policy that applies to all alerts.

expression string · min length: 1 · max length: 4096

A KQL query that's evaluated against each alert. Supported fields are: alert_id, alert_status, group_hash, last_event_timestamp, severity, and your rule's query output columns under data.* (for example, data.host.name). Referencing other fields won't work. Omit matcher.expression to match on tags alone.

tags string[] · min items: 1 · max items: 50

Routing tags this policy should match. The policy applies to alerts from any rule whose metadata.routing_tags include at least one of these tags. An empty array is not accepted. Omit matcher.tags to match on matcher.expression alone.

name string required

The name of the action policy.

snoozed_until string

The ISO datetime until which the policy is snoozed. Omitted when the policy is not snoozed.

throttle union oneOf
One of: (determined by strategy)
strategy: on_status_change

notify only on alert status transitions (default for per_alert).

strategy enum required
Values: on_status_change
updated_at string · format: date-time · max length: 64 required

The ISO datetime when the action policy was last updated.

updated_by object required

The actor who last updated the action policy.

profile_uid string required nullable

User profile ID of the actor, or null when it cannot be resolved.

Indicates an invalid schema or parameters.

application/json
code string required

Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.

details map string to object

Optional structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.

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.

Indicates the request was not authenticated.

application/json
code string required

Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.

details map string to object

Optional structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.

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.

Indicates the user does not have the required privileges, or the current license does not support action policies. Creating, updating, upserting, and enabling action policies requires an active Enterprise license. Reading, disabling, snoozing, deleting, and rotating the API key of an existing policy do not, so existing policies can still be maintained after a license lapses.

application/json
code string required

Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.

details map string to object

Optional structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.

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.

Indicates an action policy with the given ID does not exist.

application/json
code string required

Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.

details map string to object

Optional structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.

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.

Indicates the action policy was concurrently updated by another caller.

application/json
code string required

Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.

details map string to object

Optional structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.

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.

Indicates an unexpected server-side error.

application/json
code string required

Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.

details map string to object

Optional structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.

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.

Indicates the alerting engine is disabled by the alerting:v2:enabled advanced setting.

application/json
code string required

Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.

details map string to object

Optional structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.

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.

Base URL
https://{kibana_url}