---
title: "Create an action policy"
method: POST
path: "/api/alerting/v2/action_policies"
tags: ["alerting-v2"]
---

# Create an action policy

`POST /api/alerting/v2/action_policies`

**Spaces method and path for this operation:**

<div><span class="operation-verb post">post</span>&nbsp;<span class="operation-path">/s/{space_id}/api/alerting/v2/action_policies</span></div>

Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-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/.<br/><br/>[Required authorization] Route required privileges: manage_alerting-v2-action-policies AND read_alerting-v2-rules.

## Headers

- `kbn-xsrf` string, required

## Request body

- KibanaHTTPAPIsAlertingNewActionPolicy
  - `description` string, required — A description of the action policy.
  - `destinations` KibanaHTTPAPIsAlertingActionPolicyDestination[], required — The list of destinations. At least one is required.
    - `id` string, required — The workflow connector identifier.
    - `type` 'workflow', required — The destination type.
  - `group_by` string[] — The fields used to group alerts.
  - `grouping_mode` union — The grouping mode: per_episode groups by episode lifecycle, all sends a single notification for all alerts, per_field groups by the specified fields.
    - 'per_episode' — one notification per alert episode lifecycle (default).
    - 'all' — a single notification for all matching episodes.
    - 'per_field' — group by specified `groupBy` fields.
  - `matcher` string — A KQL query string to match alerts.
  - `name` string, required — The name of the action policy.
  - `tags` string[] — Tags for categorizing the action policy.
  - `throttle` KibanaHTTPAPIsAlertingActionPolicyThrottle
    - `interval` string, nullable — The throttle interval duration (e.g. 5m, 1h), or null when the strategy is intervalless.
    - `strategy` union — The throttle strategy.
      - 'on_status_change' — notify only on episode status transitions (default for `per_episode`).
      - 'per_status_interval' — notify on transitions and at regular intervals.
      - 'time_interval' — notify at regular intervals regardless of status (default for `all`/`per_field`).
      - 'every_time' — notify on every evaluation cycle (high volume).

## Response `201`

Returns the newly created action policy.

- KibanaHTTPAPIsAlertingActionPolicyResponse
  - `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, nullable, required — The user ID who created the action policy.
  - `description` string, required — A description of the action policy.
  - `destinations` KibanaHTTPAPIsAlertingActionPolicyDestination[], required — The list of destinations.
    - `id` string, required — The workflow connector identifier.
    - `type` 'workflow', required — The destination type.
  - `enabled` boolean, required — Whether the action policy is enabled.
  - `group_by` string[], nullable, required — The fields used to group alerts, or null for no grouping.
  - `grouping_mode` union, required — The grouping mode: per_episode groups by episode lifecycle, all sends a single notification for all alerts, per_field groups by the specified fields.
    - 'per_episode' — one notification per alert episode lifecycle (default).
    - 'all' — a single notification for all matching episodes.
    - 'per_field' — group by specified `groupBy` fields.
  - `id` string, required — The unique identifier for the action policy.
  - `matcher` string, nullable, required — A KQL query to match alerts, or null to match all.
  - `name` string, required — The name of the action policy.
  - `snoozed_until` string, nullable, required — The ISO datetime until which the policy is snoozed, or null if not snoozed.
  - `tags` string[], nullable, required — Tags associated with the action policy.
  - `throttle` object, nullable, required — The throttle configuration for notifications.
    - `interval` string, nullable, required — The throttle interval duration (e.g. 5m, 1h), or null when the strategy is intervalless.
    - `strategy` union — The throttle strategy.
      - 'on_status_change' — notify only on episode status transitions (default for `per_episode`).
      - 'per_status_interval' — notify on transitions and at regular intervals.
      - 'time_interval' — notify at regular intervals regardless of status (default for `all`/`per_field`).
      - 'every_time' — notify on every evaluation cycle (high volume).
  - `updated_at` string, required — The ISO datetime when the action policy was last updated.
  - `updated_by` string, nullable, required — The user ID who last updated the action policy.
  - `version` string — The version, used for optimistic concurrency control.

## Other responses

- `400` — Indicates an invalid schema or parameters.
- `401` — Indicates the request was not authenticated.
- `403` — Indicates the user does not have the required privileges to perform the request.
- `500` — Indicates an unexpected server-side error.
- `503` — Indicates the alerting engine is disabled by the `alerting:v2:enabled` advanced setting.

---

[API](https://skmtc.net/elastic/apis/kibana-apis.md) · [All operations](https://skmtc.net/elastic/apis/kibana-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/elastic/kibana-apis/revisions/34c3066fc261/schema)