kibana/docs/api/alerting/create_rule.asciidoc

[[create-rule-api]]
=== Create rule API
++++
<titleabbrev>Create rule</titleabbrev>
++++

Create {kib} rules.

WARNING: This API supports <<token-api-authentication>> only.

[[create-rule-api-request]]
==== Request

`POST <kibana host>:<port>/api/alerting/rule/<id>`

`POST <kibana host>:<port>/s/<space_id>/api/alerting/rule/<id>`

[[create-rule-api-path-params]]
==== Path parameters

`<id>`::
  (Optional, string) Specifies a UUID v1 or v4 to use instead of a randomly generated ID.

`space_id`::
  (Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.

[[create-rule-api-request-body]]
==== Request body

`name`::
  (Required, string) A name to reference and search.

`tags`::
  (Optional, string array) A list of keywords to reference and search.

`rule_type_id`::
  (Required, string) The ID of the rule type that you want to call when the rule is scheduled to run.

`schedule`::
  (Required, object) The schedule specifying when this rule should be run, using one of the available schedule formats specified under
+
._Schedule Formats_.
[%collapsible%open]
=====
A schedule is structured such that the key specifies the format you wish to use and its value specifies the schedule.

We currently support the _Interval format_ which specifies the interval in seconds, minutes, hours or days at which the rule should execute.
Example: `{ interval: "10s" }`, `{ interval: "5m" }`, `{ interval: "1h" }`, `{ interval: "1d" }`.

There are plans to support multiple other schedule formats in the near future.
=====

`throttle`::
  (Optional, string) How often this rule should fire the same actions. This will prevent the rule from sending out the same notification over and over. For example, if a rule with a `schedule` of 1 minute stays in a triggered state for 90 minutes, setting a `throttle` of `10m` or `1h` will prevent it from sending 90 notifications during this period.

`notify_when`::
  (Required, string) The condition for throttling the notification: `onActionGroupChange`, `onActiveAlert`, or `onThrottleInterval`.

`enabled`::
  (Optional, boolean) Indicates if you want to run the rule on an interval basis after it is created.

`consumer`::
  (Required, string) The name of the application that owns the rule. This name has to match the Kibana Feature name, as that dictates the required RBAC privileges.

`params`::
  (Required, object) The parameters to pass to the rule type executor `params` value. This will also validate against the rule type params validator, if defined.

`actions`::
  (Optional, object array) An array of the following action objects.
+
.Properties of the action objects:
[%collapsible%open]
=====
  `group`:::
    (Required, string) Grouping actions is recommended for escalations for different types of alerts. If you don't need this, set this value to `default`.

  `id`:::
    (Required, string) The ID of the connector saved object to execute.

  `params`:::
    (Required, object) The map to the `params` that the <<action-types,connector type>> will receive. ` params` are handled as Mustache templates and passed a default set of context.
=====


[[create-rule-api-request-codes]]
==== Response code

`200`::
    Indicates a successful call.

[[create-rule-api-example]]
==== Example

[source,sh]
--------------------------------------------------
$ curl -X POST api/alerting/rule  -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d '
{
  "params":{
      "aggType":"avg",
      "termSize":6,
      "thresholdComparator":">",
      "timeWindowSize":5,
      "timeWindowUnit":"m",
      "groupBy":"top",
      "threshold":[
         1000
      ],
      "index":[
         ".test-index"
      ],
      "timeField":"@timestamp",
      "aggField":"sheet.version",
      "termField":"name.keyword"
   },
   "consumer":"alerts",
   "rule_type_id":".index-threshold",
   "schedule":{
      "interval":"1m"
   },
   "actions":[
      {
         "id":"dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2",
         "group":"threshold met",
         "params":{
            "level":"info",
            "message":"alert '{{alertName}}' is active for group '{{context.group}}':\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{params.timeWindowSize}}{{params.timeWindowUnit}}\n- Timestamp: {{context.date}}"
         }
      }
   ],
   "tags":[
      "cpu"
   ],
   "notify_when":"onActionGroupChange",
   "name":"my alert"
}'
--------------------------------------------------
// KIBANA

The API returns the following:

[source,sh]
--------------------------------------------------
{
  "id": "41893910-6bca-11eb-9e0d-85d233e3ee35",
  "notify_when": "onActionGroupChange",
  "params": {
    "aggType": "avg",
    "termSize": 6,
    "thresholdComparator": ">",
    "timeWindowSize": 5,
    "timeWindowUnit": "m",
    "groupBy": "top",
    "threshold": [
      1000
    ],
    "index": [
      ".kibana"
    ],
    "timeField": "@timestamp",
    "aggField": "sheet.version",
    "termField": "name.keyword"
  },
  "consumer": "alerts",
  "rule_type_id": ".index-threshold",
  "schedule": {
    "interval": "1m"
  },
  "actions": [
    {
      "connector_type_id": ".server-log",
      "group": "threshold met",
      "params": {
        "level": "info",
        "message": "alert {{alertName}} is active for group {{context.group}}:\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{params.timeWindowSize}}{{params.timeWindowUnit}}\n- Timestamp: {{context.date}}"
      },
      "id": "dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2"
    }
  ],
  "tags": [
    "cpu"
  ],
  "name": "my alert",
  "enabled": true,
  "throttle": null,
  "api_key_owner": "elastic",
  "created_by": "elastic",
  "updated_by": "elastic",
  "mute_all": false,
  "muted_alert_ids": [],
  "updated_at": "2021-02-10T18:03:19.961Z",
  "created_at": "2021-02-10T18:03:19.961Z",
  "scheduled_task_id": "425b0800-6bca-11eb-9e0d-85d233e3ee35",
  "execution_status": {
    "last_execution_date": "2021-02-10T18:03:19.966Z",
    "status": "pending"
  }
}
--------------------------------------------------