Create or replace an action policy | Kibana API documentation

Create or replace an action policy Experimental; added in 9.5.0

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

Spaces method and path for this operation:

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.

[Required authorization] Route required privileges: manage_alerting-v2-action-policies AND read_alerting-v2-rules.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string Required

The identifier for the action policy.

Minimum length is 1, maximum length is 150.

application/json

Body

description string Required

A description of the action policy.

Maximum length is 1024.
destinations array[object] Required

The list of destinations. At least one is required.

At least 1 but not more than 10 elements.
Hide destinations attributes Show destinations attributes object
An action policy destination configuration.
- id string Required
  
  The workflow connector identifier.
  
  Minimum length is 1, maximum length is 150.
- type string Required Discriminator
  
  The destination type.
  
  Value is workflow.
group_by array[string]

The fields used to group alerts.

Not more than 16 elements. Minimum length of each is 1, maximum length of each is 256.
grouping_mode

Any of:
string-1 string-2 string-3

one notification per alert episode lifecycle (default).

Value is per_episode.

a single notification for all matching episodes.

Value is all.

group by specified groupBy fields.

Value is per_field.
matcher string

A KQL query string to match alerts.

Maximum length is 4096.
name string Required

The name of the action policy.

Minimum length is 1, maximum length is 256.
tags array[string]

Tags for categorizing the action policy.

Not more than 20 elements. Minimum length of each is 1, maximum length of each is 128.
throttle object

The throttle configuration for notifications.

Additional properties are NOT allowed.
Hide throttle attributes Show throttle attributes object
- interval string | null
  
  The throttle interval duration (e.g. 5m, 1h), or null when the strategy is intervalless.
- strategy string
  
  The throttle strategy.
  
  Any of:
  string-1 string string-2 string string-3 string string-4 string
  
  notify only on episode status transitions (default for per_episode).
  
  Value is on_status_change.
  
  notify on transitions and at regular intervals.
  
  Value is per_status_interval.
  
  notify at regular intervals regardless of status (default for all/per_field).
  
  Value is time_interval.
  
  notify on every evaluation cycle (high volume).
  
  Value is every_time.

Responses

200 application/json

Returns the replaced action policy.
Hide response attributes Show response attributes object
- auth object Required
  
  Authentication and ownership information.
  
  Additional properties are NOT allowed.
  
  Hide auth attributes Show auth attributes object
  
  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 | null Required
  
  The user ID who created the action policy.
- description string Required
  
  A description of the action policy.
- destinations array[object] Required
  
  The list of destinations.
  
  Hide destinations attributes Show destinations attributes object
  
  An action policy destination configuration.
  
  id string Required
  
  The workflow connector identifier.
  
  Minimum length is 1, maximum length is 150.
  
  type string Required Discriminator
  
  The destination type.
  
  Value is workflow.
- enabled boolean Required
  
  Whether the action policy is enabled.
- group_by array[string] | null Required
  
  The fields used to group alerts, or null for no grouping.
- grouping_mode string Required
  
  The grouping mode for alert notifications.
  
  Any of:
  string-1 string string-2 string string-3 string
  
  one notification per alert episode lifecycle (default).
  
  Value is per_episode.
  
  a single notification for all matching episodes.
  
  Value is all.
  
  group by specified groupBy fields.
  
  Value is per_field.
- id string Required
  
  The unique identifier for the action policy.
- matcher string | null Required
  
  A KQL query to match alerts, or null to match all.
- name string Required
  
  The name of the action policy.
- snoozed_until string | null Required
  
  The ISO datetime until which the policy is snoozed, or null if not snoozed.
- tags array[string] | null Required
  
  Tags associated with the action policy.
- throttle object | null Required
  
  The throttle configuration for notifications.
  
  Additional properties are NOT allowed.
  
  Hide throttle attributes Show throttle attributes object | null
  
  interval string | null Required
  
  The throttle interval duration (e.g. 5m, 1h), or null when the strategy is intervalless.
  
  strategy string
  
  The throttle strategy.
  
  Any of:
  string-1 string string-2 string string-3 string string-4 string
  
  notify only on episode status transitions (default for per_episode).
  
  Value is on_status_change.
  
  notify on transitions and at regular intervals.
  
  Value is per_status_interval.
  
  notify at regular intervals regardless of status (default for all/per_field).
  
  Value is time_interval.
  
  notify on every evaluation cycle (high volume).
  
  Value is every_time.
- updated_at string Required
  
  The ISO datetime when the action policy was last updated.
- updated_by string | null Required
  
  The user ID who last updated the action policy.
- version string
  
  The version, used for optimistic concurrency control.
201 application/json

Returns the newly created action policy.
Hide response attributes Show response attributes object
- auth object Required
  
  Authentication and ownership information.
  
  Additional properties are NOT allowed.
  
  Hide auth attributes Show auth attributes object
  
  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 | null Required
  
  The user ID who created the action policy.
- description string Required
  
  A description of the action policy.
- destinations array[object] Required
  
  The list of destinations.
  
  Hide destinations attributes Show destinations attributes object
  
  An action policy destination configuration.
  
  id string Required
  
  The workflow connector identifier.
  
  Minimum length is 1, maximum length is 150.
  
  type string Required Discriminator
  
  The destination type.
  
  Value is workflow.
- enabled boolean Required
  
  Whether the action policy is enabled.
- group_by array[string] | null Required
  
  The fields used to group alerts, or null for no grouping.
- grouping_mode string Required
  
  The grouping mode for alert notifications.
  
  Any of:
  string-1 string string-2 string string-3 string
  
  one notification per alert episode lifecycle (default).
  
  Value is per_episode.
  
  a single notification for all matching episodes.
  
  Value is all.
  
  group by specified groupBy fields.
  
  Value is per_field.
- id string Required
  
  The unique identifier for the action policy.
- matcher string | null Required
  
  A KQL query to match alerts, or null to match all.
- name string Required
  
  The name of the action policy.
- snoozed_until string | null Required
  
  The ISO datetime until which the policy is snoozed, or null if not snoozed.
- tags array[string] | null Required
  
  Tags associated with the action policy.
- throttle object | null Required
  
  The throttle configuration for notifications.
  
  Additional properties are NOT allowed.
  
  Hide throttle attributes Show throttle attributes object | null
  
  interval string | null Required
  
  The throttle interval duration (e.g. 5m, 1h), or null when the strategy is intervalless.
  
  strategy string
  
  The throttle strategy.
  
  Any of:
  string-1 string string-2 string string-3 string string-4 string
  
  notify only on episode status transitions (default for per_episode).
  
  Value is on_status_change.
  
  notify on transitions and at regular intervals.
  
  Value is per_status_interval.
  
  notify at regular intervals regardless of status (default for all/per_field).
  
  Value is time_interval.
  
  notify on every evaluation cycle (high volume).
  
  Value is every_time.
- updated_at string Required
  
  The ISO datetime when the action policy was last updated.
- updated_by string | null Required
  
  The user ID who last updated the action policy.
- version string
  
  The version, used for optimistic concurrency control.
400 application/json

Indicates an invalid schema or parameters.
Hide response attributes Show response attributes object
- code string Required
  
  A stable, machine-readable error code (e.g., "RULE_NOT_FOUND", "INVALID_SCHEDULE"). Safe for clients to branch on.
- details object
  
  Optional structured context (e.g., validation field errors, conflict resource IDs).
  
  Additional properties are allowed.
- 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 human-friendly explanation of the error. Subject to change without notice. Do not parse or rely on its content.
401 application/json

Indicates the request was not authenticated.
Hide response attributes Show response attributes object
- code string Required
  
  A stable, machine-readable error code (e.g., "RULE_NOT_FOUND", "INVALID_SCHEDULE"). Safe for clients to branch on.
- details object
  
  Optional structured context (e.g., validation field errors, conflict resource IDs).
  
  Additional properties are allowed.
- 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 human-friendly explanation of the error. Subject to change without notice. Do not parse or rely on its content.
403 application/json

Indicates the user does not have the required privileges to perform the request.
Hide response attributes Show response attributes object
- code string Required
  
  A stable, machine-readable error code (e.g., "RULE_NOT_FOUND", "INVALID_SCHEDULE"). Safe for clients to branch on.
- details object
  
  Optional structured context (e.g., validation field errors, conflict resource IDs).
  
  Additional properties are allowed.
- 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 human-friendly explanation of the error. Subject to change without notice. Do not parse or rely on its content.
404 application/json

Indicates an action policy with the given ID does not exist.
Hide response attributes Show response attributes object
- code string Required
  
  A stable, machine-readable error code (e.g., "RULE_NOT_FOUND", "INVALID_SCHEDULE"). Safe for clients to branch on.
- details object
  
  Optional structured context (e.g., validation field errors, conflict resource IDs).
  
  Additional properties are allowed.
- 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 human-friendly explanation of the error. Subject to change without notice. Do not parse or rely on its content.
409 application/json

Indicates the action policy was created or updated concurrently by another caller.
Hide response attributes Show response attributes object
- code string Required
  
  A stable, machine-readable error code (e.g., "RULE_NOT_FOUND", "INVALID_SCHEDULE"). Safe for clients to branch on.
- details object
  
  Optional structured context (e.g., validation field errors, conflict resource IDs).
  
  Additional properties are allowed.
- 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 human-friendly explanation of the error. Subject to change without notice. Do not parse or rely on its content.
500 application/json

Indicates an unexpected server-side error.
Hide response attributes Show response attributes object
- code string Required
  
  A stable, machine-readable error code (e.g., "RULE_NOT_FOUND", "INVALID_SCHEDULE"). Safe for clients to branch on.
- details object
  
  Optional structured context (e.g., validation field errors, conflict resource IDs).
  
  Additional properties are allowed.
- 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 human-friendly explanation of the error. Subject to change without notice. Do not parse or rely on its content.
503 application/json

Indicates the alerting engine is disabled by the alerting:v2:enabled advanced setting.
Hide response attributes Show response attributes object
- code string Required
  
  A stable, machine-readable error code (e.g., "RULE_NOT_FOUND", "INVALID_SCHEDULE"). Safe for clients to branch on.
- details object
  
  Optional structured context (e.g., validation field errors, conflict resource IDs).
  
  Additional properties are allowed.
- 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 human-friendly explanation of the error. Subject to change without notice. Do not parse or rely on its content.

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

curl \
 --request PUT 'https://localhost:5601/api/alerting/v2/action_policies/{id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '"{\n  \"description\": \"Sends a workflow notification when matching host alerts fire.\",\n  \"destinations\": [\n    {\n      \"id\": \"workflow-1\",\n      \"type\": \"workflow\"\n    }\n  ],\n  \"grouping_mode\": \"per_episode\",\n  \"matcher\": \"host.name: \\\"web-*\\\"\",\n  \"name\": \"Notify on host alerts\",\n  \"tags\": [\n    \"production\"\n  ],\n  \"throttle\": {\n    \"strategy\": \"on_status_change\"\n  }\n}"'

Request example

{
  "description": "Sends a workflow notification when matching host alerts fire.",
  "destinations": [
    {
      "id": "workflow-1",
      "type": "workflow"
    }
  ],
  "grouping_mode": "per_episode",
  "matcher": "host.name: \"web-*\"",
  "name": "Notify on host alerts",
  "tags": [
    "production"
  ],
  "throttle": {
    "strategy": "on_status_change"
  }
}

Response examples (200)

{
  "auth": {
    "created_by_user": true,
    "owner": "elastic"
  },
  "created_at": "2026-01-15T12:00:00.000Z",
  "created_by": "elastic",
  "description": "Sends a workflow notification when matching host alerts fire.",
  "destinations": [
    {
      "id": "workflow-1",
      "type": "workflow"
    }
  ],
  "enabled": true,
  "group_by": null,
  "grouping_mode": "per_episode",
  "id": "action-policy-1",
  "matcher": "host.name: \"web-*\"",
  "name": "Notify on host alerts",
  "snoozed_until": null,
  "tags": [
    "production"
  ],
  "throttle": {
    "interval": null,
    "strategy": "on_status_change"
  },
  "updated_at": "2026-01-15T12:00:00.000Z",
  "updated_by": "elastic",
  "version": "WzAsMV0="
}

Response examples (201)

{
  "auth": {
    "created_by_user": true,
    "owner": "elastic"
  },
  "created_at": "2026-01-15T12:00:00.000Z",
  "created_by": "elastic",
  "description": "Sends a workflow notification when matching host alerts fire.",
  "destinations": [
    {
      "id": "workflow-1",
      "type": "workflow"
    }
  ],
  "enabled": true,
  "group_by": null,
  "grouping_mode": "per_episode",
  "id": "action-policy-1",
  "matcher": "host.name: \"web-*\"",
  "name": "Notify on host alerts",
  "snoozed_until": null,
  "tags": [
    "production"
  ],
  "throttle": {
    "interval": null,
    "strategy": "on_status_change"
  },
  "updated_at": "2026-01-15T12:00:00.000Z",
  "updated_by": "elastic",
  "version": "WzAsMV0="
}

Response examples (400)

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

Response examples (401)

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

Response examples (403)

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

Response examples (404)

{
  "code": "ACTION_POLICY_NOT_FOUND",
  "details": {
    "action_policy_id": "action-policy-1"
  },
  "error": "Not Found",
  "message": "Action policy with id \"action-policy-1\" not found"
}

Response examples (409)

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

Response examples (500)

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

Response examples (503)

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

Create or replace an action policy Experimental; added in 9.5.0

Headers

Path parameters

Body

grouping_mode

strategy string

Responses

grouping_mode string Required

strategy string

grouping_mode string Required

strategy string