Create or replace an action policy

Base URL
https://{kibana_url}
  • PUT /api/alerting/v2/action_policies/{id}
Auth

Creates an action policy with the given identifier, or fully replaces it if one already exists.

Required privileges

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

Path parameters

id string · min length: 1 · max length: 150 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.

Header parameters

kbn-xsrf string required

A required header to protect against CSRF attacks

Request body

description string · max length: 1024 required

A description of the action policy.

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

The list of destinations. At least one is required.

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

The workflow connector identifier.

type enum required

The destination type.

Values: workflow
group_by string[] · max items: 16

The fields used to group alerts.

grouping_mode union anyOf

The grouping mode: per_episode groups by episode lifecycle, all sends a single notification for all alerts, per_field groups by the specified fields.

Values: per_episode all per_field
name string · min length: 1 · max length: 256 required

The name of the action policy.

Responses

Returns the replaced action policy.

application/json
auth object required

Authentication and ownership information.

created_by_user boolean required

Whether this policy was created by a user (vs system-generated).

owner string required

The owner of the action policy.

created_at string required

The ISO datetime when the action policy was created.

created_by string required nullable

The user ID who created the action policy.

description string required

A description of the action policy.

destinations union oneOf[] required

The list of destinations.

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

The workflow connector identifier.

type enum required

The destination type.

Values: workflow
enabled boolean required

Whether the action policy is enabled.

group_by string[] required nullable

The fields used to group alerts, or null for no grouping.

grouping_mode union anyOf required

The grouping mode for alert notifications.

Values: per_episode all per_field
id string required

The unique identifier for the action policy.

matcher object required nullable

Selects the alerts this policy applies to. Set tags to match alerts from rules with those 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. When matcher is null, or when both tags and expression are empty, the policy applies to all alerts.

expression string · max length: 4096 nullable

A KQL query that's evaluated against each alert. Supported fields are: episode_id, episode_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 or set it to null to match on tags alone.

tags string[] · max items: 50 nullable

Rule tags this policy should match. The policy applies to alerts from any rule that has at least one of these tags. Omit matcher.tags or set it to null to match on matcher.expression alone.

name string required

The name of the action policy.

snoozed_until string required nullable

The ISO datetime until which the policy is snoozed, or null if not snoozed.

throttle object required nullable

The throttle configuration for notifications.

interval string · max length: 32 required nullable

The throttle interval duration (e.g. 5m, 1h), or null when the strategy is intervalless.

strategy enum

The throttle strategy.

Values: on_status_change per_status_interval time_interval every_time
updated_at string required

The ISO datetime when the action policy was last updated.

updated_by string required nullable

The user ID who last updated the action policy.

version string

The version, used for optimistic concurrency control.

Base URL
https://{kibana_url}