Create or replace an action policy

Base URL: https://{kibana_url}

PUT /api/alerting/v2/action_policies/{id}

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

Required authorization

Authentication

Api key

Authorization: <value>

These APIs use key-based authentication. You must create an API key and use the encoded value in the request header. For example: Authorization: ApiKey base64AccessApiKey

Basic

Authorization: Basic <credentials>

Path parameters

Header parameters

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:
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.
name string · min length: 1 · max length: 256 required: The name of the action policy.
throttle object

Responses

Returns the replaced action policy.

application/json

auth object required: Authentication and ownership information.
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:
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 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.
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.
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_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:
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 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.
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.
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

Indicates the request was not authenticated.

application/json

Indicates the user does not have the required privileges to perform the request.

application/json

Indicates the action policy was created or updated concurrently by another caller.

application/json

Indicates an unexpected server-side error.

application/json

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

application/json

Base URL: https://{kibana_url}

Examples

Request Console 1 / 2 languages

Console Kibana Dev Tools

PUT kbn:/api/alerting/v2/action_policies/ID
{
  "description": "Sends notifications for alerts generated by rules with the production tag.",
  "destinations": [
    {
      "id": "workflow-1",
      "type": "workflow"
    }
  ],
  "grouping_mode": "per_episode",
  "matcher": {
    "tags": [
      "production"
    ]
  },
  "name": "Notify on production alerts",
  "throttle": {
    "strategy": "on_status_change"
  }
}

Generated from the API spec

curl Shell

curl -X PUT "${KIBANA_URL}/api/alerting/v2/action_policies/${ID}" \
  -H "kbn-xsrf: true" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Sends notifications for alerts generated by rules with the production tag.",
    "destinations": [
      {
        "id": "workflow-1",
        "type": "workflow"
      }
    ],
    "grouping_mode": "per_episode",
    "matcher": {
      "tags": [
        "production"
      ]
    },
    "name": "Notify on production alerts",
    "throttle": {
      "strategy": "on_status_change"
    }
  }'

Generated from the API spec

Response

{
  "auth": {
    "created_by_user": true,
    "owner": "elastic"
  },
  "created_at": "2026-01-15T12:00:00.000Z",
  "created_by": "elastic",
  "description": "Sends notifications for alerts generated by rules with the production tag.",
  "destinations": [
    {
      "id": "workflow-1",
      "type": "workflow"
    }
  ],
  "enabled": true,
  "group_by": "null",
  "grouping_mode": "per_episode",
  "id": "action-policy-1",
  "matcher": {
    "tags": [
      "production"
    ]
  },
  "name": "Notify on production alerts",
  "snoozed_until": "null",
  "throttle": {
    "interval": "null",
    "strategy": "on_status_change"
  },
  "updated_at": "2026-01-15T12:00:00.000Z",
  "updated_by": "elastic",
  "version": "WzAsMV0="
}

{
  "auth": {
    "created_by_user": true,
    "owner": "elastic"
  },
  "created_at": "2026-01-15T12:00:00.000Z",
  "created_by": "elastic",
  "description": "Sends notifications for alerts generated by rules with the production tag.",
  "destinations": [
    {
      "id": "workflow-1",
      "type": "workflow"
    }
  ],
  "enabled": true,
  "group_by": "null",
  "grouping_mode": "per_episode",
  "id": "action-policy-1",
  "matcher": {
    "tags": [
      "production"
    ]
  },
  "name": "Notify on production alerts",
  "snoozed_until": "null",
  "throttle": {
    "interval": "null",
    "strategy": "on_status_change"
  },
  "updated_at": "2026-01-15T12:00:00.000Z",
  "updated_by": "elastic",
  "version": "WzAsMV0="
}

{
  "code": "INVALID_ACTION_POLICY_DATA",
  "details": {
    "context": "upsert",
    "errors": {
      "errors": [],
      "properties": {
        "name": {
          "errors": [
            "Invalid input: expected string, received undefined"
          ]
        }
      }
    }
  },
  "error": "Bad Request",
  "message": "Error validating upsert action policy data - name: Invalid input: expected string, received undefined"
}

{
  "code": "UNAUTHORIZED",
  "error": "Unauthorized",
  "message": "Authentication required to access this API."
}

{
  "code": "FORBIDDEN",
  "error": "Forbidden",
  "message": "The current user does not have the required privileges for this request."
}

{
  "code": "ACTION_POLICY_VERSION_CONFLICT",
  "details": {
    "action_policy_id": "action-policy-1"
  },
  "error": "Conflict",
  "message": "Action policy with ID \u0022action-policy-1\u0022 has already been updated by another user"
}

{
  "code": "INTERNAL_SERVER_ERROR",
  "error": "Internal Server Error",
  "message": "An unexpected error occurred."
}

{
  "code": "ALERTING_DISABLED",
  "error": "Service Unavailable",
  "message": "Alerting is disabled."
}

Required authorization

Authentication

Path parameters

Header parameters

Request body { }

Responses

Request body