Create or replace an action policy | Kibana Serverless API documentation

Create or replace an action policy Experimental

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 ID of the action policy. Copy it from the response when you create a policy, fetch one policy, or fetch the policy list. Chosen at creation and permanent — it cannot be changed afterwards. Re-using the id of a deleted resource is allowed but discouraged: execution history, change history, and alert episodes recorded under that id are retained and are attributed to the new resource. Ids appear in URLs and logs, so keep them free of sensitive data.

Minimum length is 1, maximum length is 150. Format should match the following pattern: ^[a-zA-Z0-9_-]+$.

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 identifier.
  
  Minimum length is 1, maximum length is 150.
- type string Required Discriminator
  
  The destination type.
  
  Value is workflow.
enabled boolean

Whether the action policy is enabled. On create, defaults to true when omitted. On replace, omitting this field preserves the existing enabled state; otherwise it becomes the new stored value.
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 lifecycle (default).

Value is per_alert.

a single notification for all matching alerts.

Value is all.

group by specified groupBy fields.

Value is per_field.
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. When matcher is null, or when both tags and expression are empty, the policy applies to all alerts.

Additional properties are NOT allowed.
Hide matcher attributes Show matcher attributes object
- expression string | null
  
  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 under data.* (for example, data.host.name). Referencing other fields won't work. Omit matcher.expression or set it to null to match on tags alone.
  
  Maximum length is 4096.
- tags array[string] | null
  
  Routing tags this policy should match. The policy applies to alerts from any rule whose metadata.routing_tags include at least one of these tags. Omit matcher.tags or set it to null to match on matcher.expression alone.
  
  Not more than 50 elements. Minimum length of each is 1, maximum length of each is 128.
name string Required

The name of the action policy.

Minimum length is 1, maximum length is 256.
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.
  
  Maximum length is 32.
- strategy string
  The throttle strategy.
  
  Any of:
  string-1 string string-2 string string-3 string string-4 string
  
  notify only on alert status transitions (default for per_alert).
  
  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
- created_at string(date-time) Required
  
  The ISO datetime when the action policy was created.
  
  Format should match the following 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))$.
- created_by object Required
  
  The actor who created the action policy.
  
  Additional properties are NOT allowed.
  
  Hide created_by attribute Show created_by attribute object
  
  profile_uid string | null Required
  
  User profile ID of the actor, or null when it cannot be resolved.
- 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 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 lifecycle (default).
  
  Value is per_alert.
  
  a single notification for all matching alerts.
  
  Value is all.
  
  group by specified groupBy fields.
  
  Value is per_field.
- id string Required
  
  The unique identifier for the action policy.
- matcher object | null Required
  
  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. When matcher is null, or when both tags and expression are empty, the policy applies to all alerts.
  
  Additional properties are NOT allowed.
  
  Hide matcher attributes Show matcher attributes object | null
  
  expression string | null
  
  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 under data.* (for example, data.host.name). Referencing other fields won't work. Omit matcher.expression or set it to null to match on tags alone.
  
  Maximum length is 4096.
  
  tags array[string] | null
  
  Routing tags this policy should match. The policy applies to alerts from any rule whose metadata.routing_tags include at least one of these tags. Omit matcher.tags or set it to null to match on matcher.expression alone.
  
  Not more than 50 elements. Minimum length of each is 1, maximum length of each is 128.
- 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.
- 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.
  
  Maximum length is 32.
  
  strategy string
  The throttle strategy.
  
  Any of:
  string-1 string string-2 string string-3 string string-4 string
  
  notify only on alert status transitions (default for per_alert).
  
  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(date-time) Required
  
  The ISO datetime when the action policy was last updated.
  
  Format should match the following 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))$.
- updated_by object Required
  
  The actor who last updated the action policy.
  
  Additional properties are NOT allowed.
  
  Hide updated_by attribute Show updated_by attribute object
  
  profile_uid string | null Required
  
  User profile ID of the actor, or null when it cannot be resolved.
201 application/json

Returns the newly created action policy.
Hide response attributes Show response attributes object
- created_at string(date-time) Required
  
  The ISO datetime when the action policy was created.
  
  Format should match the following 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))$.
- created_by object Required
  
  The actor who created the action policy.
  
  Additional properties are NOT allowed.
  
  Hide created_by attribute Show created_by attribute object
  
  profile_uid string | null Required
  
  User profile ID of the actor, or null when it cannot be resolved.
- 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 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 lifecycle (default).
  
  Value is per_alert.
  
  a single notification for all matching alerts.
  
  Value is all.
  
  group by specified groupBy fields.
  
  Value is per_field.
- id string Required
  
  The unique identifier for the action policy.
- matcher object | null Required
  
  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. When matcher is null, or when both tags and expression are empty, the policy applies to all alerts.
  
  Additional properties are NOT allowed.
  
  Hide matcher attributes Show matcher attributes object | null
  
  expression string | null
  
  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 under data.* (for example, data.host.name). Referencing other fields won't work. Omit matcher.expression or set it to null to match on tags alone.
  
  Maximum length is 4096.
  
  tags array[string] | null
  
  Routing tags this policy should match. The policy applies to alerts from any rule whose metadata.routing_tags include at least one of these tags. Omit matcher.tags or set it to null to match on matcher.expression alone.
  
  Not more than 50 elements. Minimum length of each is 1, maximum length of each is 128.
- 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.
- 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.
  
  Maximum length is 32.
  
  strategy string
  The throttle strategy.
  
  Any of:
  string-1 string string-2 string string-3 string string-4 string
  
  notify only on alert status transitions (default for per_alert).
  
  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(date-time) Required
  
  The ISO datetime when the action policy was last updated.
  
  Format should match the following 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))$.
- updated_by object Required
  
  The actor who last updated the action policy.
  
  Additional properties are NOT allowed.
  
  Hide updated_by attribute Show updated_by attribute object
  
  profile_uid string | null Required
  
  User profile ID of the actor, or null when it cannot be resolved.
400 application/json

Indicates an invalid schema or parameters.
Hide response attributes Show response attributes object
- code string Required
  
  Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
- details object
  
  Optional extra information about the error, for example field validation issues or the rule_id when that ID already exists.
  
  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 readable explanation of the error. The wording can change without notice. Do not parse this field.
401 application/json

Indicates the request was not authenticated.
Hide response attributes Show response attributes object
- code string Required
  
  Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
- details object
  
  Optional extra information about the error, for example field validation issues or the rule_id when that ID already exists.
  
  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 readable explanation of the error. The wording can change without notice. Do not parse this field.
403 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.
Hide response attributes Show response attributes object
- code string Required
  
  Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
- details object
  
  Optional extra information about the error, for example field validation issues or the rule_id when that ID already exists.
  
  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 readable explanation of the error. The wording can change without notice. Do not parse this field.
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
  
  Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
- details object
  
  Optional extra information about the error, for example field validation issues or the rule_id when that ID already exists.
  
  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 readable explanation of the error. The wording can change without notice. Do not parse this field.
500 application/json

Indicates an unexpected server-side error.
Hide response attributes Show response attributes object
- code string Required
  
  Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
- details object
  
  Optional extra information about the error, for example field validation issues or the rule_id when that ID already exists.
  
  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 readable explanation of the error. The wording can change without notice. Do not parse this field.
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
  
  Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
- details object
  
  Optional extra information about the error, for example field validation issues or the rule_id when that ID already exists.
  
  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 readable explanation of the error. The wording can change without notice. Do not parse this field.

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

curl \
 --request PUT 'https://<KIBANA_URL>/api/alerting/v2/action_policies/{id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{
  "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"
  }
}'

Request example

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

Response examples (200)

{
  "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,
  "group_by": null,
  "grouping_mode": "per_alert",
  "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": {
    "profile_uid": "u_elastic_0"
  }
}

Response examples (201)

{
  "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,
  "group_by": null,
  "grouping_mode": "per_alert",
  "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": {
    "profile_uid": "u_elastic_0"
  }
}

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": "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": "FORBIDDEN",
  "error": "Forbidden",
  "message": "The current user does not have the required privileges for this request."
}

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