Create an action policy
https://{kibana_url}
- POST /api/alerting/v2/action_policies
- POST /s/{space_id}/api/alerting/v2/action_policies
Refer to Spaces for more information.
Creates an action policy with a server-generated identifier. To create or replace an action policy with a client-supplied identifier, use PUT /api/alerting/v2/action_policies/{id}/.
[Required authorization] Route required privileges: manage_alerting-v2-action-policies AND read_alerting-v2-rules.
Request
-
descriptionstring · min: 1 · max: 1024 -
A description of the action policy. Absent when the policy has none; send
nullon PATCH to clear it. -
destinations· min: 1 · max: 10required -
The list of destinations. At least one is required.
-
matcherobject -
Selects the alerts this policy applies to. Set
tagsto match alerts from rules with those routing tags. Setexpressionto a KQL query, which will be evaluated against each alert.
If you set bothtagsandexpression, an alert must match the tags and the expression for the policy to apply. At least one oftagsandexpressionmust be set, so an emptymatcheris rejected. Omitmatcherentirely for a catch-all policy that applies to all alerts. -
expressionstring · min: 1 · max: 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 underdata.*(for example,data.host.name). Referencing other fields won't work. Omitmatcher.expressionto match ontagsalone. -
Routing tags this policy should match. The policy applies to alerts from any rule whose
metadata.routing_tagsinclude at least one of these tags. An empty array is not accepted. Omitmatcher.tagsto match onmatcher.expressionalone. -
namestring · min: 1 · max: 256required -
The name of the action policy.
-
throttle -
strategy -
Values:
on_status_change -
strategy -
Values:
every_time
strategy: on_status_change
notify only on alert status transitions (default for per_alert).
strategy: per_status_interval
notify on transitions and at regular intervals.
strategy: time_interval
notify at regular intervals regardless of status (default for all/per_field).
strategy: every_time
notify on every evaluation cycle (high volume).
Responses
Returns the newly created action policy.
-
created_atstring · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$required -
The ISO datetime when the action policy was created.
-
created_by -
The actor who created the action policy.
-
profile_uidstringrequired nullable -
User profile ID of the actor, or
nullwhen it cannot be resolved. -
descriptionstring -
A description of the action policy. Omitted when the policy has none.
-
destinations -
The list of destinations.
-
enabledbooleanrequired -
Whether the action policy is enabled.
-
idstringrequired -
The unique identifier for the action policy.
-
matcherobject -
Selects the alerts this policy applies to. Set
tagsto match alerts from rules with those routing tags. Setexpressionto a KQL query, which will be evaluated against each alert.
If you set bothtagsandexpression, an alert must match the tags and the expression for the policy to apply. At least one oftagsandexpressionmust be set, so an emptymatcheris rejected. Omitmatcherentirely for a catch-all policy that applies to all alerts. -
expressionstring · min: 1 · max: 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 underdata.*(for example,data.host.name). Referencing other fields won't work. Omitmatcher.expressionto match ontagsalone. -
Routing tags this policy should match. The policy applies to alerts from any rule whose
metadata.routing_tagsinclude at least one of these tags. An empty array is not accepted. Omitmatcher.tagsto match onmatcher.expressionalone. -
namestringrequired -
The name of the action policy.
-
snoozed_untilstring -
The ISO datetime until which the policy is snoozed. Omitted when the policy is not snoozed.
-
throttle -
strategy -
Values:
on_status_change -
strategy -
Values:
every_time -
updated_atstring · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$required -
The ISO datetime when the action policy was last updated.
-
updated_by -
The actor who last updated the action policy.
-
profile_uidstringrequired nullable -
User profile ID of the actor, or
nullwhen it cannot be resolved.
strategy: on_status_change
notify only on alert status transitions (default for per_alert).
strategy: per_status_interval
notify on transitions and at regular intervals.
strategy: time_interval
notify at regular intervals regardless of status (default for all/per_field).
strategy: every_time
notify on every evaluation cycle (high volume).
Indicates an invalid schema or parameters.
-
codestringrequired -
Stable error code you can branch on, for example
INVALID_SCHEDULEorRULE_ALREADY_EXISTS. -
detailsmap string to object -
Optional extra information about the error, for example field validation issues or the
rule_idwhen that ID already exists. -
errorstringrequired -
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.
-
messagestringrequired -
A readable explanation of the error. The wording can change without notice. Do not parse this field.
Indicates the request was not authenticated.
-
codestringrequired -
Stable error code you can branch on, for example
INVALID_SCHEDULEorRULE_ALREADY_EXISTS. -
detailsmap string to object -
Optional extra information about the error, for example field validation issues or the
rule_idwhen that ID already exists. -
errorstringrequired -
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.
-
messagestringrequired -
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, and enabling action policies requires an active Enterprise license.
-
codestringrequired -
Stable error code you can branch on, for example
INVALID_SCHEDULEorRULE_ALREADY_EXISTS. -
detailsmap string to object -
Optional extra information about the error, for example field validation issues or the
rule_idwhen that ID already exists. -
errorstringrequired -
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.
-
messagestringrequired -
A readable explanation of the error. The wording can change without notice. Do not parse this field.
Indicates an unexpected server-side error.
-
codestringrequired -
Stable error code you can branch on, for example
INVALID_SCHEDULEorRULE_ALREADY_EXISTS. -
detailsmap string to object -
Optional extra information about the error, for example field validation issues or the
rule_idwhen that ID already exists. -
errorstringrequired -
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.
-
messagestringrequired -
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.
-
codestringrequired -
Stable error code you can branch on, for example
INVALID_SCHEDULEorRULE_ALREADY_EXISTS. -
detailsmap string to object -
Optional extra information about the error, for example field validation issues or the
rule_idwhen that ID already exists. -
errorstringrequired -
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.
-
messagestringrequired -
A readable explanation of the error. The wording can change without notice. Do not parse this field.