[role="xpack"]
[[watcher-api-put-watch]]
=== Put watch API
++++
<titleabbrev>Put watch</titleabbrev>
++++

The PUT watch API either registers a new watch in {watcher} or updates an
existing one.

[float]
==== Request

`PUT _watcher/watch/<watch_id>`

[float]
==== Description

When a watch is registered, a new document that represents the watch is added to
the `.watches` index and its trigger is immediately registered with the relevant
trigger engine. Typically for the `schedule` trigger, the scheduler is the
trigger engine.

IMPORTANT:  You must use {kib} or this API to create a watch. Do not put a watch
            directly to the `.watches` index using the Elasticsearch index API.
            If {es} {security-features} are enabled, do not give users `write`
            privileges on the `.watches` index.

When adding a watch you can also define its initial
{stack-ov}/how-watcher-works.html#watch-active-state[active state]. You do that
by setting the `active` parameter.

[float]
==== Path Parameters

`watch_id` (required)::
  (string) Identifier for the watch.

[float]
==== Query Parameters

`active`::
  (boolean) Defines whether the watch is active or inactive by default. The
  default value is `true`, which means the watch is active by default.

[float]
==== Request Body

A watch has the following fields:

[options="header"]
|======
| Name              | Description

| `trigger`         | The {stack-ov}/trigger.html[trigger] that defines when
                      the watch should run.

| `input`           | The {stack-ov}/input.html[input] that defines the input
                      that loads the data for the watch.

| `condition`       | The {stack-ov}/condition.html[condition] that defines if
                      the actions should be run.

| `actions`         | The list of {stack-ov}/actions.html[actions] that will be
                      run if the condition matches

| `metadata`        | Metadata json that will be copied into the history entries.

| `throttle_period` | The minimum time between actions being run, the default
                      for this is 5 seconds. This default can be changed in the
                      config file with the setting
                      `xpack.watcher.throttle.period.default_period`. If both
                      this value and the `throttle_period_in_millis` parameter
                      are specified, {watcher} uses the last parameter
                      included in the request.

| `throttle_period_in_millis` | Minimum time in milliseconds between actions
                                being run. Defaults to `5000`. If both this
                                value and the `throttle_period` parameter are
                                specified, {watcher} uses the last parameter
                                included in the request.

|======

[float]
==== Authorization

You must have `manage_watcher` cluster privileges to use this API. For more
information, see {stack-ov}/security-privileges.html[Security Privileges].

[float]
==== Security Integration

When {es} {security-features} are enabled, your watch can index or search only
on indices for which the user that stored the watch has privileges. If the user
is able to read index `a`, but not index `b`, the same will apply, when the watch
is executed.

[float]
==== Examples

The following example adds a watch with the `my-watch` id that has the following
characteristics:

* The watch schedule triggers every minute.
* The watch search input looks for any 404 HTTP responses that occurred in the
  last five minutes.
* The watch condition checks if any search hits where found.
* When found, the watch action sends an email to an administrator.

[source,js]
--------------------------------------------------
PUT _watcher/watch/my-watch
{
  "trigger" : {
    "schedule" : { "cron" : "0 0/1 * * * ?" }
  },
  "input" : {
    "search" : {
      "request" : {
        "indices" : [
          "logstash*"
        ],
        "body" : {
          "query" : {
            "bool" : {
              "must" : {
                "match": {
                   "response": 404
                }
              },
              "filter" : {
                "range": {
                  "@timestamp": {
                    "from": "{{ctx.trigger.scheduled_time}}||-5m",
                    "to": "{{ctx.trigger.triggered_time}}"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "condition" : {
    "compare" : { "ctx.payload.hits.total" : { "gt" : 0 }}
  },
  "actions" : {
    "email_admin" : {
      "email" : {
        "to" : "admin@domain.host.com",
        "subject" : "404 recently encountered"
      }
    }
  }
}
--------------------------------------------------
// CONSOLE

When you add a watch you can also define its initial
{stack-ov}/how-watcher-works.html#watch-active-state[active state]. You do that
by setting the `active` parameter. The following command adds a watch and sets
it to be inactive by default:

[source,js]
--------------------------------------------------
PUT _watcher/watch/my-watch?active=false
--------------------------------------------------

NOTE: If you omit the `active` parameter, the watch is active by default.