# Create or update a watch


**POST /_watcher/watch/{id}**

**All methods and paths for this operation:**

<div>
                      <span class="operation-verb put">PUT</span>
                      <span class="operation-path">/_watcher/watch/{id}</span>
                      </div>
                    <div>
                      <span class="operation-verb post">POST</span>
                      <span class="operation-path">/_watcher/watch/{id}</span>
                      </div>
                    

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 Kibana or this API to create a watch.
Do not add a watch directly to the `.watches` index by using the Elasticsearch index API.
If Elasticsearch security features are enabled, do not give users write privileges on the `.watches` index.

When you add a watch you can also define its initial active state by setting the *active* parameter.

When Elasticsearch 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 runs.

## Required authorization

* Cluster privileges: `manage_watcher`



## Servers
- http://api.example.com: http://api.example.com ()


## Authentication methods
- Api key auth
- Basic auth
- Bearer auth


## Parameters

### Path parameters
- **id** (string)
  The identifier for the watch.

### Query parameters
- **active** (boolean)
  The initial state of the watch.
  The default value is `true`, which means the watch is active by default.
- **if_primary_term** (number)
  Only update the watch if the last operation that has changed the watch has the specified primary term
- **if_seq_no** (number)
  Only update the watch if the last operation that has changed the watch has the specified sequence number
- **version** (number)
  Explicit version number for concurrency control

### Body: application/json (object)

- **actions** (object)
  The list of actions that will be run if the condition matches.
- **condition** (object)
  The condition that defines if the actions should be run.
- **input** (object)
  The input that defines the input that loads the data for the watch.
- **metadata** (object)
  Metadata JSON that will be copied into the history entries.
- **throttle_period** (string)
  The minimum time between actions being run.
  The default 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** (number)
  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.
- **transform** (object)
  The transform that processes the watch payload to prepare it for the watch actions.
- **trigger** (object)
  The trigger that defines when the watch should run.


## Responses
### 200


#### Body: application/json (object)
- **created** (boolean)

- **_id** (string)

- **_primary_term** (number)

- **_seq_no** (number)

- **_version** (number)



[Powered by Bump.sh](https://bump.sh)