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 authorization

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
matcher object

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 · min length: 1 · max length: 256 required

The name of the action policy.

throttle object
interval string · max length: 32 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

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.

Returns the newly created 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.

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 extra information about the error, for example field validation issues or the rule_id when that ID already exists.

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 extra information about the error, for example field validation issues or the rule_id when that ID already exists.

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 to perform the request.

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 extra information about the error, for example field validation issues or the rule_id when that ID already exists.

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 created or updated concurrently 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 extra information about the error, for example field validation issues or the rule_id when that ID already exists.

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 extra information about the error, for example field validation issues or the rule_id when that ID already exists.

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 extra information about the error, for example field validation issues or the rule_id when that ID already exists.

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}