Partially update an action policy.

Server: https://{kibana_url}

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

Refer to Spaces for more information.

Apply a partial update. A field you omit keeps its stored value, and that applies at every level: send {"matcher": {"tags": ["prod"]}} to change one leaf while leaving its siblings alone. Send null to clear a field, again at any level: {"matcher": {"expression": null}} clears a single leaf, while {"matcher": null} clears a whole object. Lists and variant objects are replaced as a unit rather than merged, since a partly-sent variant could never be valid. The merged result is validated as a whole, so a patch that would leave the resource invalid is rejected with a 400 and nothing is stored.

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

Path Parameters

id string · min: 1 · max: 150 · pattern: ^[a-zA-Z0-9_-]+$ 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.

Request

description string · min: 1 · max: 1024 nullable: A description of the action policy. Absent when the policy has none; send null on PATCH to clear it.
destinations [] union · min: 1 · max: 10: The list of destinations. At least one is required.; One of:
grouping object: How matched alerts are batched into notifications. Absent falls back to per_alert; send null on PATCH to clear it. The mode decides the rest of the block, so a PATCH replaces it whole: send the complete mode variant rather than a single field.
matcher object nullable: 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. Omit matcher to keep the stored matcher, or set it to null for a catch-all policy that applies to all alerts. An empty matcher names no leaf and so changes nothing; clearing the last of tags and expression clears the matcher itself, which is also a catch-all.
name string · min: 1 · max: 256: The name of the action policy.
throttle object: The throttle configuration for notifications. Absent when notifications are not throttled; send null on PATCH to clear it. The strategy decides the rest of the block, so a PATCH replaces it whole: send the complete strategy variant rather than a single field.

Responses

Returns the updated action policy.

application/json

created_at string · 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))$ required: The ISO datetime when the action policy was created.
created_by {} required: The actor who created the action policy.
description string: A description of the action policy. Omitted when the policy has none.
destinations [] union required: The list of destinations.; One of:
enabled boolean required: Whether the action policy is enabled.
grouping union: 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: One of: (determined by strategy)
updated_at string · 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))$ required: The ISO datetime when the action policy was last updated.
updated_by {} 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 an action policy with the given ID does not exist.

application/json

Indicates the action policy was concurrently updated 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

Examples

Request Console 1 / 2 languages

Console Kibana Dev Tools

PATCH /api/alerting/v2/action_policies/{id}
{
  "description": "Updated description.",
  "matcher": {
    "expression": "null",
    "tags": [
      "production"
    ]
  },
  "name": "Notify on production alerts (updated)"
}

curl Shell

curl -X PATCH "https://{kibana_url}/api/alerting/v2/action_policies/{id}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Updated description.",
  "matcher": {
    "expression": "null",
    "tags": [
      "production"
    ]
  },
  "name": "Notify on production alerts (updated)"
}'

Response

{
  "created_at": "2026-01-15T12:00:00.000Z",
  "created_by": {
    "profile_uid": "u_elastic_0"
  },
  "description": "Updated description.",
  "destinations": [
    {
      "id": "workflow-1",
      "type": "workflow"
    }
  ],
  "enabled": true,
  "grouping": {
    "mode": "per_alert"
  },
  "id": "action-policy-1",
  "matcher": {
    "tags": [
      "production"
    ]
  },
  "name": "Notify on production alerts (updated)",
  "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": "update",
    "errors": {
      "errors": [],
      "properties": {
        "name": {
          "errors": [
            "Invalid input: expected string, received undefined"
          ]
        }
      }
    }
  },
  "error": "Bad Request",
  "message": "Error validating update 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_NOT_FOUND",
  "details": {
    "action_policy_id": "action-policy-1"
  },
  "error": "Not Found",
  "message": "Action policy with ID \u0022action-policy-1\u0022 not found"
}

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

Path Parameters

Request { description , destinations , grouping , matcher , name , throttle , }

Responses

Request