Create or replace an action policy

Base URL: https://{kibana_url}

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

Refer to Spaces for more information.

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

Request body

description string · min length: 1 · max length: 1024: A description of the action policy. Absent when the policy has none; send null on PATCH to clear it.
destinations union oneOf[] · min items: 1 · max items: 10 required: The list of destinations. At least one is required.; One of:
grouping union oneOf: One of: (determined by mode)
matcher object: Selects the alerts this policy applies to. Set tags to match alerts from rules with those routing 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. At least one of tags and expression must be set, so an empty matcher is rejected. Omit matcher entirely for a catch-all policy that applies to all alerts.
name string · min length: 1 · max length: 256 required: The name of the action policy.
throttle union oneOf: One of: (determined by strategy)

Responses

Returns the replaced action policy.

application/json

created_at string · format: date-time required: The ISO datetime when the action policy was created.
created_by object required: The actor who created the action policy.
description string: A description of the action policy. Omitted when the policy has none.
destinations union oneOf[] required: The list of destinations.; One of:
enabled boolean required: Whether the action policy is enabled.
grouping union oneOf: One of: (determined by mode)
id string required: The unique identifier for the action policy.
matcher object: Selects the alerts this policy applies to. Set tags to match alerts from rules with those routing 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. At least one of tags and expression must be set, so an empty matcher is rejected. Omit matcher entirely for a catch-all policy that applies to all alerts.
name string required: The name of the action policy.
snoozed_until string: The ISO datetime until which the policy is snoozed. Omitted when the policy is not snoozed.
throttle union oneOf: One of: (determined by strategy)
updated_at string · format: date-time required: The ISO datetime when the action policy was last updated.
updated_by object required: The actor who last updated the action policy.

Returns the newly created action policy.

application/json

created_at string · format: date-time required: The ISO datetime when the action policy was created.
created_by object required: The actor who created the action policy.
description string: A description of the action policy. Omitted when the policy has none.
destinations union oneOf[] required: The list of destinations.; One of:
enabled boolean required: Whether the action policy is enabled.
grouping union oneOf: One of: (determined by mode)
id string required: The unique identifier for the action policy.
matcher object: Selects the alerts this policy applies to. Set tags to match alerts from rules with those routing 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. At least one of tags and expression must be set, so an empty matcher is rejected. Omit matcher entirely for a catch-all policy that applies to all alerts.
name string required: The name of the action policy.
snoozed_until string: The ISO datetime until which the policy is snoozed. Omitted when the policy is not snoozed.
throttle union oneOf: One of: (determined by strategy)
updated_at string · format: date-time required: The ISO datetime when the action policy was last updated.
updated_by object required: The actor who last updated the action policy.

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, or the current license does not support action policies. Creating, updating, and enabling action policies requires an active Enterprise license.

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_alert"
  },
  "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_alert"
    },
    "matcher": {
      "tags": [
        "production"
      ]
    },
    "name": "Notify on production alerts",
    "throttle": {
      "strategy": "on_status_change"
    }
  }'

Generated from the API spec

Response

{
  "created_at": "2026-01-15T12:00:00.000Z",
  "created_by": {
    "profile_uid": "u_elastic_0"
  },
  "description": "Sends notifications for alerts generated by rules with the production tag.",
  "destinations": [
    {
      "id": "workflow-1",
      "type": "workflow"
    }
  ],
  "enabled": true,
  "grouping": {
    "mode": "per_alert"
  },
  "id": "action-policy-1",
  "matcher": {
    "tags": [
      "production"
    ]
  },
  "name": "Notify on production alerts",
  "throttle": {
    "strategy": "on_status_change"
  },
  "updated_at": "2026-01-15T12:00:00.000Z",
  "updated_by": {
    "profile_uid": "u_elastic_0"
  }
}

{
  "created_at": "2026-01-15T12:00:00.000Z",
  "created_by": {
    "profile_uid": "u_elastic_0"
  },
  "description": "Sends notifications for alerts generated by rules with the production tag.",
  "destinations": [
    {
      "id": "workflow-1",
      "type": "workflow"
    }
  ],
  "enabled": true,
  "grouping": {
    "mode": "per_alert"
  },
  "id": "action-policy-1",
  "matcher": {
    "tags": [
      "production"
    ]
  },
  "name": "Notify on production alerts",
  "throttle": {
    "strategy": "on_status_change"
  },
  "updated_at": "2026-01-15T12:00:00.000Z",
  "updated_by": {
    "profile_uid": "u_elastic_0"
  }
}

{
  "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": "ACTION_POLICY_LICENSE_NOT_SUPPORTED",
  "details": {
    "current_license": "basic",
    "license_status": "active",
    "required_license": "enterprise"
  },
  "error": "Forbidden",
  "message": "Action policies require an active enterprise license"
}

{
  "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."
}

Create or replace an action policy

Required authorization

Authentication

Path parameters

Header parameters

Request body

Responses

Required authorization

Authentication

Path parameters

Header parameters

Request body { }

Responses

Request body