Partially update an action policy. Experimental

PATCH /api/alerting/v2/action_policies/{id}
Api key auth

Spaces method and path for this operation:

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.

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 alerts 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 | null

    A description of the action policy. Absent when the policy has none; send null on PATCH to clear it.

    Minimum length is 1, maximum length is 1024.

  • destinations array[object]

    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.

  • grouping

    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.

    Hide grouping attributes Show grouping attributes
    • mode Required Discriminator
    • fields array[string] Required

      The fields alerts are grouped by. At least one is required, and no other mode accepts them.

      At least 1 but not more than 16 elements. Minimum length of each is 1, maximum length of each is 256.

  • matcher object | null

    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.

    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 to keep the stored expression, or set it to null to clear it and match on tags alone.

      Minimum length is 1, 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. An empty array is not accepted. Omit matcher.tags to keep the stored tags, or set it to null to clear them and match on matcher.expression alone.

      At least 1 but not more than 50 elements. Minimum length of each is 1, maximum length of each is 128.

  • name string

    The name of the action policy.

    Minimum length is 1, maximum length is 256.

  • throttle

    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.

    Hide throttle attributes Show throttle attributes
    • strategy Required Discriminator
    • interval string Required

      The throttle interval duration (e.g. 5m, 1h) that sets the notification cadence.

      Maximum length is 32.

Responses

  • 200 application/json

    Returns the updated action policy.

    Hide response attributes Show response attributes object
    • created_at string(date-time) Required

      The ISO datetime when the action policy was created.

    • 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

      A description of the action policy. Omitted when the policy has none.

    • 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.

    • grouping object
      One of:
      object object object
    • 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.

      Additional properties are NOT allowed.

      Hide matcher attributes Show matcher attributes object
      • expression string

        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 to match on tags alone.

        Minimum length is 1, maximum length is 4096.

      • tags array[string]

        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. An empty array is not accepted. Omit matcher.tags to match on matcher.expression alone.

        At least 1 but 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

      The ISO datetime until which the policy is snoozed. Omitted when the policy is not snoozed.

    • throttle object
      One of:
      object object object object
    • updated_at string(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.

      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.
  • 404 application/json

    Indicates an action policy with the given ID does not exist.

    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 concurrently updated 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.
PATCH /api/alerting/v2/action_policies/{id} 
curl \
 --request PATCH 'https://<KIBANA_URL>/api/alerting/v2/action_policies/{id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{
  "description": "Updated description.",
  "matcher": {
    "expression": null,
    "tags": [
      "production"
    ]
  },
  "name": "Notify on production alerts (updated)"
}'
Request example 
{
  "description": "Updated description.",
  "matcher": {
    "expression": null,
    "tags": [
      "production"
    ]
  },
  "name": "Notify on production alerts (updated)"
}
Response examples (200) 
{
  "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"
  }
}
Response examples (400) 
{
  "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"
}
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 (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."
}