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

Either registers a new watch in {watcher} or updates an existing one.

[[watcher-api-put-watch-request]]
==== {api-request-title}

`PUT _watcher/watch/<watch_id>`

[[watcher-api-put-watch-prereqs]]
==== {api-prereq-title}

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

[[watcher-api-put-watch-desc]]
==== {api-description-title}

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.

[[watcher-api-put-watch-security]]
===== 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.

[[watcher-api-put-watch-path-params]]
==== {api-path-parms-title}

`<watch_id>`::
  (Required, string) Identifier for the watch.

[[watcher-api-put-watch-query-params]]
==== {api-query-parms-title}

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

[[watcher-api-put-watch-request-body]]
==== {api-request-body-title}

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.

|======

//[[watcher-api-put-watch-response-body]]
//==== {api-response-body-title}

//[[watcher-api-put-watch-response-codes]]
//==== {api-response-codes-title}

[[watcher-api-put-watch-example]]
==== {api-examples-title}

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,console]
--------------------------------------------------
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"
      }
    }
  }
}
--------------------------------------------------

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.