Create or update a watch

PUT /_watcher/watch/{id}
Api key auth Basic auth Bearer auth

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.

Path parameters

  • id string Required

    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

application/json

Body

Responses

PUT /_watcher/watch/{id} 
curl \
 --request PUT 'http://api.example.com/_watcher/watch/{id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"trigger\" : {\n    \"schedule\" : { \"cron\" : \"0 0/1 * * * ?\" }\n  },\n  \"input\" : {\n    \"search\" : {\n      \"request\" : {\n        \"indices\" : [\n          \"logstash*\"\n        ],\n        \"body\" : {\n          \"query\" : {\n            \"bool\" : {\n              \"must\" : {\n                \"match\": {\n                  \"response\": 404\n                }\n              },\n              \"filter\" : {\n                \"range\": {\n                  \"@timestamp\": {\n                    \"from\": \"{{ctx.trigger.scheduled_time}}||-5m\",\n                    \"to\": \"{{ctx.trigger.triggered_time}}\"\n                  }\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  },\n  \"condition\" : {\n    \"compare\" : { \"ctx.payload.hits.total\" : { \"gt\" : 0 }}\n  },\n  \"actions\" : {\n    \"email_admin\" : {\n      \"email\" : {\n        \"to\" : \"admin@domain.host.com\",\n        \"subject\" : \"404 recently encountered\"\n      }\n    }\n  }\n}"'
Request example
Run `PUT _watcher/watch/my-watch` add a watch. 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. 
{
  "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"
      }
    }
  }
}
Response examples (200) 
{
  "created": true,
  "_id": "string",
  "_primary_term": 42.0,
  "_seq_no": 42.0,
  "_version": 42.0
}