Create or replace a rule

Base URL: https://{kibana_url}

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

Refer to Spaces for more information.

Creates a rule with the given identifier, or fully replaces it if one already exists.

Required authorization

Authentication

Api key

Authorization: <value>

These APIs use key-based authentication. You must create an API key and use the encoded value in the request header. For example: Authorization: ApiKey base64AccessApiKey

Basic

Authorization: Basic <credentials>

Path parameters

Header parameters

Request body

artifacts object[] · min items: 1 · max items: 100: Optional objects attached to the rule, such as a runbook or a dashboard. Each item has id, type, and data. The shape of data depends on type. For example, a runbook uses content and a dashboard uses dashboard_id. Known types are validated against that shape. Unknown types are stored when id, type, and data are present. An empty array is rejected: omit artifacts on create, or send null on PATCH to clear.
grouping object: Grouping configuration.
kind enum required: Whether the rule creates alerts (alert) or only stores matching events (signal).; Values: alert signal
metadata object required: Rule metadata.
no_data union oneOf: What the rule does when a group has no data. Required when kind is alert. Not allowed when kind is signal. Any strategy other than ignore requires either query.breach or no_data.query, so that a group with no data can be told apart from one that stopped breaching.; One of: (determined by strategy)
query object required: ES|QL query the rule evaluates. base is required. breach is an optional clause appended to it.
recovery union oneOf: When an alert recovers. Required when kind is alert. Not allowed when kind is signal.; One of: (determined by strategy)
schedule object required: Execution schedule configuration.
state_transition object: Specifies how many consecutive matches, or how long a condition must hold, before an alert becomes active or inactive. Allowed only when kind is alert.
time_field string · min length: 1 · max length: 256 · default: @timestamp: Document field Kibana uses with schedule.lookback to time-filter query.base.

Responses

Returns the replaced rule.

application/json

artifacts object[] · min items: 1 · max items: 100: Optional objects attached to the rule, such as a runbook or a dashboard. Each item has id, type, and data. The shape of data depends on type. For example, a runbook uses content and a dashboard uses dashboard_id. Known types are validated against that shape. Unknown types are stored when id, type, and data are present. An empty array is rejected: omit artifacts on create, or send null on PATCH to clear.
created_at string · format: date-time required: ISO timestamp when the rule was created.
created_by object required: Actor who created the rule.
enabled boolean required: Whether the rule is enabled.
grouping object: Grouping configuration.
id string required: Unique rule identifier.
kind enum required: Whether the rule creates alerts (alert) or only stores matching events (signal).; Values: alert signal
metadata object required: Rule metadata.
no_data union oneOf: What the rule does when a group has no data. Required when kind is alert. Not allowed when kind is signal. Any strategy other than ignore requires either query.breach or no_data.query, so that a group with no data can be told apart from one that stopped breaching.; One of: (determined by strategy)
query object required: ES|QL query the rule evaluates. base is required. breach is an optional clause appended to it.
recovery union oneOf: When an alert recovers. Required when kind is alert. Not allowed when kind is signal.; One of: (determined by strategy)
schedule object required: Execution schedule configuration.
state_transition object: Specifies how many consecutive matches, or how long a condition must hold, before an alert becomes active or inactive. Allowed only when kind is alert.
time_field string · min length: 1 · max length: 256 · default: @timestamp: Document field Kibana uses with schedule.lookback to time-filter query.base.
updated_at string · format: date-time required: ISO timestamp when the rule was last updated.
updated_by object required: Actor who last updated the rule.
version integer · min: 1 · max: 9007199254740991 required: Monotonically increasing integer number representing a rule configuration version, incremented on every change. Used on generated rule events as rule.version.

Returns the newly created rule.

application/json

artifacts object[] · min items: 1 · max items: 100: Optional objects attached to the rule, such as a runbook or a dashboard. Each item has id, type, and data. The shape of data depends on type. For example, a runbook uses content and a dashboard uses dashboard_id. Known types are validated against that shape. Unknown types are stored when id, type, and data are present. An empty array is rejected: omit artifacts on create, or send null on PATCH to clear.
created_at string · format: date-time required: ISO timestamp when the rule was created.
created_by object required: Actor who created the rule.
enabled boolean required: Whether the rule is enabled.
grouping object: Grouping configuration.
id string required: Unique rule identifier.
kind enum required: Whether the rule creates alerts (alert) or only stores matching events (signal).; Values: alert signal
metadata object required: Rule metadata.
no_data union oneOf: What the rule does when a group has no data. Required when kind is alert. Not allowed when kind is signal. Any strategy other than ignore requires either query.breach or no_data.query, so that a group with no data can be told apart from one that stopped breaching.; One of: (determined by strategy)
query object required: ES|QL query the rule evaluates. base is required. breach is an optional clause appended to it.
recovery union oneOf: When an alert recovers. Required when kind is alert. Not allowed when kind is signal.; One of: (determined by strategy)
schedule object required: Execution schedule configuration.
state_transition object: Specifies how many consecutive matches, or how long a condition must hold, before an alert becomes active or inactive. Allowed only when kind is alert.
time_field string · min length: 1 · max length: 256 · default: @timestamp: Document field Kibana uses with schedule.lookback to time-filter query.base.
updated_at string · format: date-time required: ISO timestamp when the rule was last updated.
updated_by object required: Actor who last updated the rule.
version integer · min: 1 · max: 9007199254740991 required: Monotonically increasing integer number representing a rule configuration version, incremented on every change. Used on generated rule events as rule.version.

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 to perform the request.

application/json

Indicates the rule was created or updated concurrently, or the request changes immutable fields.

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/rules/ID
{
  "grouping": {
    "fields": [
      "host.name"
    ]
  },
  "kind": "alert",
  "metadata": {
    "description": "Alerts when average CPU usage exceeds a threshold.",
    "name": "Host CPU high",
    "routing_tags": [
      "sre-oncall"
    ],
    "tags": [
      "production",
      "infra"
    ]
  },
  "no_data": {
    "strategy": "keep_last"
  },
  "query": {
    "base": "FROM metrics-* | STATS avg_cpu = AVG(host.cpu.usage) BY host.name",
    "breach": {
      "segment": "WHERE avg_cpu \u003E 0.9"
    }
  },
  "recovery": {
    "strategy": "no_breach"
  },
  "schedule": {
    "every": "1m",
    "lookback": "5m"
  },
  "state_transition": {
    "pending": {
      "count": 1
    },
    "recovering": {
      "count": 1
    }
  },
  "time_field": "@timestamp"
}

Generated from the API spec

curl Shell

curl -X PUT "${KIBANA_URL}/api/alerting/v2/rules/${ID}" \
  -H "kbn-xsrf: true" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "grouping": {
      "fields": [
        "host.name"
      ]
    },
    "kind": "alert",
    "metadata": {
      "description": "Alerts when average CPU usage exceeds a threshold.",
      "name": "Host CPU high",
      "routing_tags": [
        "sre-oncall"
      ],
      "tags": [
        "production",
        "infra"
      ]
    },
    "no_data": {
      "strategy": "keep_last"
    },
    "query": {
      "base": "FROM metrics-* | STATS avg_cpu = AVG(host.cpu.usage) BY host.name",
      "breach": {
        "segment": "WHERE avg_cpu \u003E 0.9"
      }
    },
    "recovery": {
      "strategy": "no_breach"
    },
    "schedule": {
      "every": "1m",
      "lookback": "5m"
    },
    "state_transition": {
      "pending": {
        "count": 1
      },
      "recovering": {
        "count": 1
      }
    },
    "time_field": "@timestamp"
  }'

Generated from the API spec

Response

{
  "created_at": "2026-01-15T12:00:00.000Z",
  "created_by": {
    "profile_uid": "u_elastic_0"
  },
  "enabled": true,
  "grouping": {
    "fields": [
      "host.name"
    ]
  },
  "id": "rule-1",
  "kind": "alert",
  "metadata": {
    "description": "Alerts when average CPU usage exceeds a threshold.",
    "name": "Host CPU high",
    "routing_tags": [
      "sre-oncall"
    ],
    "tags": [
      "production",
      "infra"
    ]
  },
  "no_data": {
    "strategy": "keep_last"
  },
  "query": {
    "base": "FROM metrics-* | STATS avg_cpu = AVG(host.cpu.usage) BY host.name",
    "breach": {
      "segment": "WHERE avg_cpu \u003E 0.9"
    }
  },
  "recovery": {
    "strategy": "no_breach"
  },
  "schedule": {
    "every": "1m",
    "lookback": "5m"
  },
  "state_transition": {
    "pending": {
      "count": 1
    },
    "recovering": {
      "count": 1
    }
  },
  "time_field": "@timestamp",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "updated_by": {
    "profile_uid": "u_elastic_0"
  },
  "version": 1
}

{
  "created_at": "2026-01-15T12:00:00.000Z",
  "created_by": {
    "profile_uid": "u_elastic_0"
  },
  "enabled": true,
  "grouping": {
    "fields": [
      "host.name"
    ]
  },
  "id": "rule-1",
  "kind": "alert",
  "metadata": {
    "description": "Alerts when average CPU usage exceeds a threshold.",
    "name": "Host CPU high",
    "routing_tags": [
      "sre-oncall"
    ],
    "tags": [
      "production",
      "infra"
    ]
  },
  "no_data": {
    "strategy": "keep_last"
  },
  "query": {
    "base": "FROM metrics-* | STATS avg_cpu = AVG(host.cpu.usage) BY host.name",
    "breach": {
      "segment": "WHERE avg_cpu \u003E 0.9"
    }
  },
  "recovery": {
    "strategy": "no_breach"
  },
  "schedule": {
    "every": "1m",
    "lookback": "5m"
  },
  "state_transition": {
    "pending": {
      "count": 1
    },
    "recovering": {
      "count": 1
    }
  },
  "time_field": "@timestamp",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "updated_by": {
    "profile_uid": "u_elastic_0"
  },
  "version": 1
}

{
  "code": "BAD_REQUEST",
  "details": {
    "errors": {
      "metadata": [
        "Required"
      ]
    }
  },
  "error": "Bad Request",
  "message": "metadata: Required"
}

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

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

{
  "code": "RULE_VERSION_CONFLICT",
  "details": {
    "rule_id": "rule-1"
  },
  "error": "Conflict",
  "message": "Rule with id \u0022rule-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."
}

Required authorization

Authentication

Path parameters

Header parameters

Request body { }

Responses

Request body