Create or replace a rule Experimental; added in 9.5.0

PUT /api/alerting/v2/rules/{id}
Api key auth Basic auth

Spaces method and path for this operation:

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] Route required privileges: manage_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 rule.

    Minimum length is 1, maximum length is 150.

application/json

Body

  • artifacts array[object]

    Artifacts attached to the rule, each shaped as { id, type, data }. data is a type-specific object (for example a runbook may carry content, a dashboard may carry dashboardId). Per-type shape is validated by the artifact-type registry when the type is registered; unregistered types pass through with envelope bounds only.

    Not more than 100 elements.

    Hide artifacts attributes Show artifacts attributes object
    • data object Required

      Structured artifact data.

      Additional properties are allowed.

    • id string Required

      Artifact identifier.

      Minimum length is 1, maximum length is 256.

    • type string Required

      Artifact type.

      Minimum length is 1, maximum length is 128.

  • grouping object

    Grouping configuration.

    Additional properties are NOT allowed.

    Hide grouping attribute Show grouping attribute object
    • fields array[string] Required

      Fields to group alerts by, e.g. ["host.name", "service.name"]. Should match ES|QL GROUP BY fields.

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

  • kind string Required

    The kind of the rule.

    Any of:
    string-1 string string-2 string

    Default. Tracks each problem as an alert episode and its lifecycle, link it to workflows to notify your team. Use when the user wants to detect and respond.

    Value is alert.

    Matches are stored as queryable events. No alerts, no notifications - just data. Use when the user wants to collect evidence.

    Value is signal.

  • metadata object Required

    Rule metadata.

    Additional properties are NOT allowed.

    Hide metadata attributes Show metadata attributes object
    • builder_type string

      Identifies the rule builder that authored this rule (e.g. "threshold"). Absent for rules authored directly in ES|QL.

      Maximum length is 64.

    • description string

      Human-readable description of the rule.

      Maximum length is 1024.

    • name string Required

      Rule name (must be unique within the space).

      Minimum length is 1, maximum length is 256.

    • owner string

      Owner of the rule.

      Maximum length is 256.

    • tags array[string]

      Tags for categorization, e.g. ["production", "infra"].

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

  • no_data_strategy string

    How to handle no-data situations. "last_known_status" holds the last known status; "recover" forces recovery; "none" disables no-data detection. "emit" is not currently accepted by the create/update API. Standalone-format rules must provide a no_data query block when this is not "none"; composed-format rules use base as the data-presence query.

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

    Holds the last known episode status when no data is present.

    Value is last_known_status.

    Emits a no_data alert event when no_data query returns no rows for the group. "emit" is not currently accepted by the create/update API.

    Value is emit.

    Resolves the alert episode to inactive on the first no-data run.

    Value is recover.

    No-data situations are ignored (default).

    Value is none.

  • query object Required

    Detection query configuration.

    One of:
    composed object standalone object

  • recovery_strategy string

    How recovery is detected. "no_breach" recovers groups that stop breaching; "query" uses a custom recovery query; "none" disables recovery.

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

    recovers groups that stop breaching (default).

    Value is no_breach.

    uses a custom recovery query to detect recovery.

    Value is query.

    disables recovery entirely.

    Value is none.

  • schedule object Required

    Execution schedule configuration.

    Additional properties are NOT allowed.

    Hide schedule attributes Show schedule attributes object
    • every string Required

      Execution interval, e.g. 1m, 5m, 1h.

    • lookback string

      Lookback window for the query, e.g. 5m, 1h. Can also be expressed in ES|QL.

  • state_transition object | null

    Episode state transition thresholds (alert-only).

    Additional properties are NOT allowed.

    Hide state_transition attributes Show state_transition attributes object | null
    • pending_count integer

      Consecutive breaches before transitioning to active.

      Minimum value is 0, maximum value is 1000.

    • pending_operator string

      How to combine count and timeframe for pending.

      Values are AND or OR.

    • pending_timeframe string

      Time window for pending evaluation, e.g. 5m, 15m.

    • recovering_count integer

      Consecutive recoveries before transitioning to inactive.

      Minimum value is 0, maximum value is 1000.

    • recovering_operator string

      How to combine count and timeframe for recovering.

      Values are AND or OR.

    • recovering_timeframe string

      Time window for recovering evaluation, e.g. 5m, 15m.

  • time_field string

    Time field used for the lookback window range filter.

    Minimum length is 1, maximum length is 128. Default value is @timestamp.

Responses

  • 200 application/json

    Returns the replaced rule.

    Hide response attributes Show response attributes object
    • artifacts array[object]

      Artifacts attached to the rule, each shaped as { id, type, data }. data is a type-specific object (for example a runbook may carry content, a dashboard may carry dashboardId). Per-type shape is validated by the artifact-type registry when the type is registered; unregistered types pass through with envelope bounds only.

      Not more than 100 elements.

      Hide artifacts attributes Show artifacts attributes object
      • data object Required

        Structured artifact data.

        Additional properties are allowed.

      • id string Required

        Artifact identifier.

        Minimum length is 1, maximum length is 256.

      • type string Required

        Artifact type.

        Minimum length is 1, maximum length is 128.

    • created_at string Required

      ISO timestamp when the rule was created.

    • created_by string | null Required

      User who created the rule.

    • enabled boolean Required

      Whether the rule is enabled.

    • grouping object

      Grouping configuration.

      Additional properties are NOT allowed.

      Hide grouping attribute Show grouping attribute object
      • fields array[string] Required

        Fields to group alerts by, e.g. ["host.name", "service.name"]. Should match ES|QL GROUP BY fields.

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

    • id string Required

      Unique rule identifier.

    • kind string Required

      The kind of the rule.

      Any of:
      string-1 string string-2 string

      Default. Tracks each problem as an alert episode and its lifecycle, link it to workflows to notify your team. Use when the user wants to detect and respond.

      Value is alert.

      Matches are stored as queryable events. No alerts, no notifications - just data. Use when the user wants to collect evidence.

      Value is signal.

    • metadata object Required

      Additional properties are NOT allowed.

      Hide metadata attributes Show metadata attributes object
      • builder_type string

        Identifies the rule builder that authored this rule (e.g. "threshold"). Absent for rules authored directly in ES|QL.

        Maximum length is 64.

      • description string

        Human-readable description of the rule.

        Maximum length is 1024.

      • name string Required

        Rule name (must be unique within the space).

        Minimum length is 1, maximum length is 256.

      • owner string

        Owner of the rule.

        Maximum length is 256.

      • tags array[string]

        Tags for categorization, e.g. ["production", "infra"].

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

      • version integer Required

        Monotonically increasing integer number representing a rule configuration version, incremented on every change. Used on generated rule events as rule.version.

        Minimum value is 1, maximum value is 9007199254740991.

    • no_data_strategy string

      How to handle no-data situations. "last_known_status" holds the last known status; "recover" forces recovery; "none" disables no-data detection. "emit" is not currently accepted by the create/update API. Standalone-format rules must provide a no_data query block when this is not "none"; composed-format rules use base as the data-presence query.

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

      Holds the last known episode status when no data is present.

      Value is last_known_status.

      Emits a no_data alert event when no_data query returns no rows for the group. "emit" is not currently accepted by the create/update API.

      Value is emit.

      Resolves the alert episode to inactive on the first no-data run.

      Value is recover.

      No-data situations are ignored (default).

      Value is none.

    • query object Required

      Detection query configuration.

      One of:
      composed object standalone object

    • recovery_strategy string

      How recovery is detected. "no_breach" recovers groups that stop breaching; "query" uses a custom recovery query; "none" disables recovery.

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

      recovers groups that stop breaching (default).

      Value is no_breach.

      uses a custom recovery query to detect recovery.

      Value is query.

      disables recovery entirely.

      Value is none.

    • schedule object Required

      Execution schedule configuration.

      Additional properties are NOT allowed.

      Hide schedule attributes Show schedule attributes object
      • every string Required

        Execution interval, e.g. 1m, 5m, 1h.

      • lookback string

        Lookback window for the query, e.g. 5m, 1h. Can also be expressed in ES|QL.

    • state_transition object | null

      Episode state transition thresholds (alert-only).

      Additional properties are NOT allowed.

      Hide state_transition attributes Show state_transition attributes object | null
      • pending_count integer

        Consecutive breaches before transitioning to active.

        Minimum value is 0, maximum value is 1000.

      • pending_operator string

        How to combine count and timeframe for pending.

        Values are AND or OR.

      • pending_timeframe string

        Time window for pending evaluation, e.g. 5m, 15m.

      • recovering_count integer

        Consecutive recoveries before transitioning to inactive.

        Minimum value is 0, maximum value is 1000.

      • recovering_operator string

        How to combine count and timeframe for recovering.

        Values are AND or OR.

      • recovering_timeframe string

        Time window for recovering evaluation, e.g. 5m, 15m.

    • time_field string

      Time field used for the lookback window range filter.

      Minimum length is 1, maximum length is 128. Default value is @timestamp.

    • updated_at string Required

      ISO timestamp when the rule was last updated.

    • updated_by string | null Required

      User who last updated the rule.

    • version string

      The saved object version token of the rule, used for optimistic concurrency control.
  • 201 application/json

    Returns the newly created rule.

    Hide response attributes Show response attributes object
    • artifacts array[object]

      Artifacts attached to the rule, each shaped as { id, type, data }. data is a type-specific object (for example a runbook may carry content, a dashboard may carry dashboardId). Per-type shape is validated by the artifact-type registry when the type is registered; unregistered types pass through with envelope bounds only.

      Not more than 100 elements.

      Hide artifacts attributes Show artifacts attributes object
      • data object Required

        Structured artifact data.

        Additional properties are allowed.

      • id string Required

        Artifact identifier.

        Minimum length is 1, maximum length is 256.

      • type string Required

        Artifact type.

        Minimum length is 1, maximum length is 128.

    • created_at string Required

      ISO timestamp when the rule was created.

    • created_by string | null Required

      User who created the rule.

    • enabled boolean Required

      Whether the rule is enabled.

    • grouping object

      Grouping configuration.

      Additional properties are NOT allowed.

      Hide grouping attribute Show grouping attribute object
      • fields array[string] Required

        Fields to group alerts by, e.g. ["host.name", "service.name"]. Should match ES|QL GROUP BY fields.

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

    • id string Required

      Unique rule identifier.

    • kind string Required

      The kind of the rule.

      Any of:
      string-1 string string-2 string

      Default. Tracks each problem as an alert episode and its lifecycle, link it to workflows to notify your team. Use when the user wants to detect and respond.

      Value is alert.

      Matches are stored as queryable events. No alerts, no notifications - just data. Use when the user wants to collect evidence.

      Value is signal.

    • metadata object Required

      Additional properties are NOT allowed.

      Hide metadata attributes Show metadata attributes object
      • builder_type string

        Identifies the rule builder that authored this rule (e.g. "threshold"). Absent for rules authored directly in ES|QL.

        Maximum length is 64.

      • description string

        Human-readable description of the rule.

        Maximum length is 1024.

      • name string Required

        Rule name (must be unique within the space).

        Minimum length is 1, maximum length is 256.

      • owner string

        Owner of the rule.

        Maximum length is 256.

      • tags array[string]

        Tags for categorization, e.g. ["production", "infra"].

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

      • version integer Required

        Monotonically increasing integer number representing a rule configuration version, incremented on every change. Used on generated rule events as rule.version.

        Minimum value is 1, maximum value is 9007199254740991.

    • no_data_strategy string

      How to handle no-data situations. "last_known_status" holds the last known status; "recover" forces recovery; "none" disables no-data detection. "emit" is not currently accepted by the create/update API. Standalone-format rules must provide a no_data query block when this is not "none"; composed-format rules use base as the data-presence query.

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

      Holds the last known episode status when no data is present.

      Value is last_known_status.

      Emits a no_data alert event when no_data query returns no rows for the group. "emit" is not currently accepted by the create/update API.

      Value is emit.

      Resolves the alert episode to inactive on the first no-data run.

      Value is recover.

      No-data situations are ignored (default).

      Value is none.

    • query object Required

      Detection query configuration.

      One of:
      composed object standalone object

    • recovery_strategy string

      How recovery is detected. "no_breach" recovers groups that stop breaching; "query" uses a custom recovery query; "none" disables recovery.

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

      recovers groups that stop breaching (default).

      Value is no_breach.

      uses a custom recovery query to detect recovery.

      Value is query.

      disables recovery entirely.

      Value is none.

    • schedule object Required

      Execution schedule configuration.

      Additional properties are NOT allowed.

      Hide schedule attributes Show schedule attributes object
      • every string Required

        Execution interval, e.g. 1m, 5m, 1h.

      • lookback string

        Lookback window for the query, e.g. 5m, 1h. Can also be expressed in ES|QL.

    • state_transition object | null

      Episode state transition thresholds (alert-only).

      Additional properties are NOT allowed.

      Hide state_transition attributes Show state_transition attributes object | null
      • pending_count integer

        Consecutive breaches before transitioning to active.

        Minimum value is 0, maximum value is 1000.

      • pending_operator string

        How to combine count and timeframe for pending.

        Values are AND or OR.

      • pending_timeframe string

        Time window for pending evaluation, e.g. 5m, 15m.

      • recovering_count integer

        Consecutive recoveries before transitioning to inactive.

        Minimum value is 0, maximum value is 1000.

      • recovering_operator string

        How to combine count and timeframe for recovering.

        Values are AND or OR.

      • recovering_timeframe string

        Time window for recovering evaluation, e.g. 5m, 15m.

    • time_field string

      Time field used for the lookback window range filter.

      Minimum length is 1, maximum length is 128. Default value is @timestamp.

    • updated_at string Required

      ISO timestamp when the rule was last updated.

    • updated_by string | null Required

      User who last updated the rule.

    • version string

      The saved object version token of the rule, 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 a rule 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 rule was created or updated concurrently, or the request changes immutable fields.

    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/rules/{id} 
curl \
 --request PUT 'https://localhost:5601/api/alerting/v2/rules/{id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '"{\n  \"grouping\": {\n    \"fields\": [\n      \"host.name\"\n    ]\n  },\n  \"kind\": \"alert\",\n  \"metadata\": {\n    \"description\": \"Alerts when average CPU usage exceeds a threshold.\",\n    \"name\": \"Host CPU high\",\n    \"tags\": [\n      \"production\",\n      \"infra\"\n    ]\n  },\n  \"query\": {\n    \"breach\": {\n      \"query\": \"FROM metrics-* | WHERE host.cpu.usage \u003e 0.9 | STATS avg_cpu = AVG(host.cpu.usage) BY host.name\"\n    },\n    \"format\": \"standalone\"\n  },\n  \"recovery_strategy\": \"no_breach\",\n  \"schedule\": {\n    \"every\": \"1m\",\n    \"lookback\": \"5m\"\n  },\n  \"state_transition\": {\n    \"pending_count\": 1,\n    \"recovering_count\": 1\n  },\n  \"time_field\": \"@timestamp\"\n}"'
Request example 
{
  "grouping": {
    "fields": [
      "host.name"
    ]
  },
  "kind": "alert",
  "metadata": {
    "description": "Alerts when average CPU usage exceeds a threshold.",
    "name": "Host CPU high",
    "tags": [
      "production",
      "infra"
    ]
  },
  "query": {
    "breach": {
      "query": "FROM metrics-* | WHERE host.cpu.usage > 0.9 | STATS avg_cpu = AVG(host.cpu.usage) BY host.name"
    },
    "format": "standalone"
  },
  "recovery_strategy": "no_breach",
  "schedule": {
    "every": "1m",
    "lookback": "5m"
  },
  "state_transition": {
    "pending_count": 1,
    "recovering_count": 1
  },
  "time_field": "@timestamp"
}
Response examples (200) 
{
  "created_at": "2026-01-15T12:00:00.000Z",
  "created_by": "elastic",
  "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",
    "tags": [
      "production",
      "infra"
    ],
    "version": 1
  },
  "query": {
    "breach": {
      "query": "FROM metrics-* | WHERE host.cpu.usage > 0.9 | STATS avg_cpu = AVG(host.cpu.usage) BY host.name"
    },
    "format": "standalone"
  },
  "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": "elastic",
  "version": "WzAsMV0="
}
Response examples (201) 
{
  "created_at": "2026-01-15T12:00:00.000Z",
  "created_by": "elastic",
  "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",
    "tags": [
      "production",
      "infra"
    ],
    "version": 1
  },
  "query": {
    "breach": {
      "query": "FROM metrics-* | WHERE host.cpu.usage > 0.9 | STATS avg_cpu = AVG(host.cpu.usage) BY host.name"
    },
    "format": "standalone"
  },
  "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": "elastic",
  "version": "WzAsMV0="
}
Response examples (400) 
{
  "code": "BAD_REQUEST",
  "details": {
    "errors": {
      "metadata": [
        "Required"
      ]
    }
  },
  "error": "Bad Request",
  "message": "metadata: Required"
}
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": "RULE_NOT_FOUND",
  "details": {
    "rule_id": "rule-1"
  },
  "error": "Not Found",
  "message": "Rule with id \"rule-1\" not found"
}
Response examples (409) 
{
  "code": "RULE_VERSION_CONFLICT",
  "details": {
    "rule_id": "rule-1"
  },
  "error": "Conflict",
  "message": "Rule with id \"rule-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."
}