Create or update a watch

PUT /_watcher/watch/{id}

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

    Watch ID

Query parameters

  • active boolean

    Specify whether the watch is in/active by default

  • only update the watch if the last operation that has changed the watch has the specified primary term

  • 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

  • actions object
    Hide actions attribute Show actions attribute object
    • * object Additional properties

      Additional properties are allowed.

      Hide * attributes Show * attributes object
      • Values are email, webhook, index, logging, slack, or pagerduty.

      • Additional properties are allowed.

        Hide condition attributes Show condition attributes object
        • always object

          Additional properties are allowed.

        • Hide array_compare attribute Show array_compare attribute object
          • * object Additional properties

            Additional properties are allowed.

            Hide * attribute Show * attribute object
        • compare object
          Hide compare attribute Show compare attribute object
          • * object Additional properties
        • never object

          Additional properties are allowed.

        • script object

          Additional properties are allowed.

          Hide script attributes Show script attributes object
          • lang string
          • params object
            Hide params attribute Show params attribute object
            • * object Additional properties

              Additional properties are allowed.

          • source string
          • id string
      • foreach string
      • name string
      • A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

      • Time unit for milliseconds

      • Additional properties are allowed.

        Hide transform attributes Show transform attributes object
        • chain array[object]

          Additional properties are allowed.

        • script object

          Additional properties are allowed.

          Hide script attributes Show script attributes object
          • lang string
          • params object
            Hide params attribute Show params attribute object
            • * object Additional properties

              Additional properties are allowed.

          • source string
          • id string
      • index object

        Additional properties are allowed.

        Hide index attributes Show index attributes object
        • index string Required
        • doc_id string
        • refresh string

          Values are true, false, or wait_for.

        • op_type string

          Values are index or create.

        • timeout string

          A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

        • Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

      • logging object

        Additional properties are allowed.

        Hide logging attributes Show logging attributes object
      • email object

        Additional properties are allowed.

        Hide email attributes Show email attributes object
        • id string
        • bcc array[string]
        • body object

          Additional properties are allowed.

          Hide body attributes Show body attributes object
        • cc array[string]
        • from string
        • priority string

          Values are lowest, low, normal, high, or highest.

        • reply_to array[string]
        • sent_date string | number

          A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.

        • subject string Required
        • to array[string] Required
        • Hide attachments attribute Show attachments attribute object
          • * object Additional properties

            Additional properties are allowed.

            Hide * attributes Show * attributes object
            • http object

              Additional properties are allowed.

            • Additional properties are allowed.

            • data object

              Additional properties are allowed.

      • Additional properties are allowed.

        Hide pagerduty attributes Show pagerduty attributes object
      • slack object

        Additional properties are allowed.

        Hide slack attributes Show slack attributes object
      • webhook object

        Additional properties are allowed.

        Hide webhook attributes Show webhook attributes object
        • auth object

          Additional properties are allowed.

          Hide auth attribute Show auth attribute object
          • basic object Required

            Additional properties are allowed.

            Hide basic attributes Show basic attributes object
        • body string
        • A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

        • headers object
          Hide headers attribute Show headers attribute object
          • * string Additional properties
        • host string
        • method string

          Values are head, get, post, put, or delete.

        • params object
          Hide params attribute Show params attribute object
          • * string Additional properties
        • path string
        • port number
        • proxy object

          Additional properties are allowed.

          Hide proxy attributes Show proxy attributes object
        • A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

        • scheme string

          Values are http or https.

        • url string
  • Additional properties are allowed.

    Hide condition attributes Show condition attributes object
    • always object

      Additional properties are allowed.

    • Hide array_compare attribute Show array_compare attribute object
      • * object Additional properties

        Additional properties are allowed.

        Hide * attribute Show * attribute object
    • compare object
      Hide compare attribute Show compare attribute object
      • * object Additional properties
    • never object

      Additional properties are allowed.

    • script object

      Additional properties are allowed.

      Hide script attributes Show script attributes object
      • lang string
      • params object
        Hide params attribute Show params attribute object
        • * object Additional properties

          Additional properties are allowed.

      • source string
      • id string
  • input object

    Additional properties are allowed.

    Hide input attributes Show input attributes object
    • chain object

      Additional properties are allowed.

      Hide chain attribute Show chain attribute object
      • inputs array[object] Required
        Hide inputs attribute Show inputs attribute object
        • * object

          Additional properties are allowed.

    • http object

      Additional properties are allowed.

      Hide http attributes Show http attributes object
      • extract array[string]
      • request object

        Additional properties are allowed.

        Hide request attributes Show request attributes object
        • auth object

          Additional properties are allowed.

          Hide auth attribute Show auth attribute object
          • basic object Required

            Additional properties are allowed.

            Hide basic attributes Show basic attributes object
        • body string
        • A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

        • headers object
          Hide headers attribute Show headers attribute object
          • * string Additional properties
        • host string
        • method string

          Values are head, get, post, put, or delete.

        • params object
          Hide params attribute Show params attribute object
          • * string Additional properties
        • path string
        • port number
        • proxy object

          Additional properties are allowed.

          Hide proxy attributes Show proxy attributes object
        • A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

        • scheme string

          Values are http or https.

        • url string
      • Values are json, yaml, or text.

    • simple object
      Hide simple attribute Show simple attribute object
      • * object Additional properties

        Additional properties are allowed.

  • metadata object
    Hide metadata attribute Show metadata attribute object
    • * object Additional properties

      Additional properties are allowed.

  • Additional properties are allowed.

    Hide transform attributes Show transform attributes object
    • chain array[object]

      Additional properties are allowed.

    • script object

      Additional properties are allowed.

      Hide script attributes Show script attributes object
      • lang string
      • params object
        Hide params attribute Show params attribute object
        • * object Additional properties

          Additional properties are allowed.

      • source string
      • id string
  • trigger object

    Additional properties are allowed.

    Hide trigger attribute Show trigger attribute object
    • schedule object

      Additional properties are allowed.

      Hide schedule attributes Show schedule attributes object

Responses

PUT /_watcher/watch/{id}
curl \
 -X PUT http://api.example.com/_watcher/watch/{id} \
 -H "Content-Type: application/json" \
 -d '{"actions":{"additionalProperty1":{"action_type":"email","condition":{"always":{},"array_compare":{"additionalProperty1":{"path":"string"},"additionalProperty2":{"path":"string"}},"compare":{"additionalProperty1":{},"additionalProperty2":{}},"never":{},"script":{"lang":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"source":"string","id":"string"}},"foreach":"string","max_iterations":42.0,"name":"string","throttle_period":"string","":{"auth":{"basic":{"password":"string","username":"string"}},"body":"string","connection_timeout":"string","headers":{"additionalProperty1":"string","additionalProperty2":"string"},"host":"string","method":"head","params":{"additionalProperty1":"string","additionalProperty2":"string"},"path":"string","port":42.0,"proxy":{"host":"string","port":42.0},"read_timeout":"string","scheme":"http","url":"string"},"transform":{"chain":[{}],"script":{"lang":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"source":"string","id":"string"},"search":{"request":{"body":{"query":{}},"indices":["string"],"indices_options":{"allow_no_indices":true,"expand_wildcards":"string","ignore_unavailable":true,"ignore_throttled":true},"search_type":"query_then_fetch","template":{"explain":true,"id":"string","params":{},"profile":true,"source":"string"},"rest_total_hits_as_int":true},"timeout":"string"}},"index":{"index":"string","doc_id":"string","refresh":"true","op_type":"index","timeout":"string","execution_time_field":"string"},"logging":{"level":"string","text":"string","category":"string"},"slack":{"account":"string","message":{"attachments":[{"author_icon":"string","author_link":"string","author_name":"string","color":"string","fallback":"string","fields":[{}],"footer":"string","footer_icon":"string","image_url":"string","pretext":"string","text":"string","thumb_url":"string","title":"string","title_link":"string"}],"dynamic_attachments":{"attachment_template":{"author_icon":"string","author_link":"string","author_name":"string","color":"string","fallback":"string","fields":[{}],"footer":"string","footer_icon":"string","image_url":"string","pretext":"string","text":"string","thumb_url":"string","title":"string","title_link":"string"},"list_path":"string"},"from":"string","icon":"string","text":"string","to":["string"]}}},"additionalProperty2":{"action_type":"email","condition":{"always":{},"array_compare":{"additionalProperty1":{"path":"string"},"additionalProperty2":{"path":"string"}},"compare":{"additionalProperty1":{},"additionalProperty2":{}},"never":{},"script":{"lang":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"source":"string","id":"string"}},"foreach":"string","max_iterations":42.0,"name":"string","throttle_period":"string","":{"auth":{"basic":{"password":"string","username":"string"}},"body":"string","connection_timeout":"string","headers":{"additionalProperty1":"string","additionalProperty2":"string"},"host":"string","method":"head","params":{"additionalProperty1":"string","additionalProperty2":"string"},"path":"string","port":42.0,"proxy":{"host":"string","port":42.0},"read_timeout":"string","scheme":"http","url":"string"},"transform":{"chain":[{}],"script":{"lang":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"source":"string","id":"string"},"search":{"request":{"body":{"query":{}},"indices":["string"],"indices_options":{"allow_no_indices":true,"expand_wildcards":"string","ignore_unavailable":true,"ignore_throttled":true},"search_type":"query_then_fetch","template":{"explain":true,"id":"string","params":{},"profile":true,"source":"string"},"rest_total_hits_as_int":true},"timeout":"string"}},"index":{"index":"string","doc_id":"string","refresh":"true","op_type":"index","timeout":"string","execution_time_field":"string"},"logging":{"level":"string","text":"string","category":"string"},"slack":{"account":"string","message":{"attachments":[{"author_icon":"string","author_link":"string","author_name":"string","color":"string","fallback":"string","fields":[{}],"footer":"string","footer_icon":"string","image_url":"string","pretext":"string","text":"string","thumb_url":"string","title":"string","title_link":"string"}],"dynamic_attachments":{"attachment_template":{"author_icon":"string","author_link":"string","author_name":"string","color":"string","fallback":"string","fields":[{}],"footer":"string","footer_icon":"string","image_url":"string","pretext":"string","text":"string","thumb_url":"string","title":"string","title_link":"string"},"list_path":"string"},"from":"string","icon":"string","text":"string","to":["string"]}}}},"condition":{"always":{},"array_compare":{"additionalProperty1":{"path":"string"},"additionalProperty2":{"path":"string"}},"compare":{"additionalProperty1":{},"additionalProperty2":{}},"never":{},"script":{"lang":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"source":"string","id":"string"}},"input":{"chain":{"inputs":[{"*":{}}]},"http":{"extract":["string"],"request":{"auth":{"basic":{"password":"string","username":"string"}},"body":"string","connection_timeout":"string","headers":{"additionalProperty1":"string","additionalProperty2":"string"},"host":"string","method":"head","params":{"additionalProperty1":"string","additionalProperty2":"string"},"path":"string","port":42.0,"proxy":{"host":"string","port":42.0},"read_timeout":"string","scheme":"http","url":"string"},"response_content_type":"json"},"search":{"extract":["string"],"request":{"body":{"query":{}},"indices":["string"],"indices_options":{"allow_no_indices":true,"expand_wildcards":"string","ignore_unavailable":true,"ignore_throttled":true},"search_type":"query_then_fetch","template":{"explain":true,"id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"profile":true,"source":"string"},"rest_total_hits_as_int":true},"timeout":"string"},"simple":{"additionalProperty1":{},"additionalProperty2":{}}},"metadata":{"additionalProperty1":{},"additionalProperty2":{}},"throttle_period":"string","transform":{"chain":[{}],"script":{"lang":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"source":"string","id":"string"},"search":{"request":{"body":{"query":{}},"indices":["string"],"indices_options":{"allow_no_indices":true,"expand_wildcards":"string","ignore_unavailable":true,"ignore_throttled":true},"search_type":"query_then_fetch","template":{"explain":true,"id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"profile":true,"source":"string"},"rest_total_hits_as_int":true},"timeout":"string"}},"trigger":{"schedule":{"timezone":"string","cron":"string","daily":{"at":["string"]},"hourly":{"minute":[42.0]},"interval":"string","monthly":{"at":["string"],"on":[42.0]},"weekly":{"at":["string"],"on":["sunday"]},"yearly":{"at":["string"],"int":["january"],"on":[42.0]}}}}'
Request examples
{
  "actions": {
    "additionalProperty1": {
      "action_type": "email",
      "condition": {
        "always": {},
        "array_compare": {
          "additionalProperty1": {
            "path": "string"
          },
          "additionalProperty2": {
            "path": "string"
          }
        },
        "compare": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "never": {},
        "script": {
          "lang": "string",
          "params": {
            "additionalProperty1": {},
            "additionalProperty2": {}
          },
          "source": "string",
          "id": "string"
        }
      },
      "foreach": "string",
      "max_iterations": 42.0,
      "name": "string",
      "throttle_period": "string",
      "": {
        "auth": {
          "basic": {
            "password": "string",
            "username": "string"
          }
        },
        "body": "string",
        "connection_timeout": "string",
        "headers": {
          "additionalProperty1": "string",
          "additionalProperty2": "string"
        },
        "host": "string",
        "method": "head",
        "params": {
          "additionalProperty1": "string",
          "additionalProperty2": "string"
        },
        "path": "string",
        "port": 42.0,
        "proxy": {
          "host": "string",
          "port": 42.0
        },
        "read_timeout": "string",
        "scheme": "http",
        "url": "string"
      },
      "transform": {
        "chain": [
          {}
        ],
        "script": {
          "lang": "string",
          "params": {
            "additionalProperty1": {},
            "additionalProperty2": {}
          },
          "source": "string",
          "id": "string"
        },
        "search": {
          "request": {
            "body": {
              "query": {}
            },
            "indices": [
              "string"
            ],
            "indices_options": {
              "allow_no_indices": true,
              "expand_wildcards": "string",
              "ignore_unavailable": true,
              "ignore_throttled": true
            },
            "search_type": "query_then_fetch",
            "template": {
              "explain": true,
              "id": "string",
              "params": {},
              "profile": true,
              "source": "string"
            },
            "rest_total_hits_as_int": true
          },
          "timeout": "string"
        }
      },
      "index": {
        "index": "string",
        "doc_id": "string",
        "refresh": "true",
        "op_type": "index",
        "timeout": "string",
        "execution_time_field": "string"
      },
      "logging": {
        "level": "string",
        "text": "string",
        "category": "string"
      },
      "slack": {
        "account": "string",
        "message": {
          "attachments": [
            {
              "author_icon": "string",
              "author_link": "string",
              "author_name": "string",
              "color": "string",
              "fallback": "string",
              "fields": [
                {}
              ],
              "footer": "string",
              "footer_icon": "string",
              "image_url": "string",
              "pretext": "string",
              "text": "string",
              "thumb_url": "string",
              "title": "string",
              "title_link": "string"
            }
          ],
          "dynamic_attachments": {
            "attachment_template": {
              "author_icon": "string",
              "author_link": "string",
              "author_name": "string",
              "color": "string",
              "fallback": "string",
              "fields": [
                {}
              ],
              "footer": "string",
              "footer_icon": "string",
              "image_url": "string",
              "pretext": "string",
              "text": "string",
              "thumb_url": "string",
              "title": "string",
              "title_link": "string"
            },
            "list_path": "string"
          },
          "from": "string",
          "icon": "string",
          "text": "string",
          "to": [
            "string"
          ]
        }
      }
    },
    "additionalProperty2": {
      "action_type": "email",
      "condition": {
        "always": {},
        "array_compare": {
          "additionalProperty1": {
            "path": "string"
          },
          "additionalProperty2": {
            "path": "string"
          }
        },
        "compare": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "never": {},
        "script": {
          "lang": "string",
          "params": {
            "additionalProperty1": {},
            "additionalProperty2": {}
          },
          "source": "string",
          "id": "string"
        }
      },
      "foreach": "string",
      "max_iterations": 42.0,
      "name": "string",
      "throttle_period": "string",
      "": {
        "auth": {
          "basic": {
            "password": "string",
            "username": "string"
          }
        },
        "body": "string",
        "connection_timeout": "string",
        "headers": {
          "additionalProperty1": "string",
          "additionalProperty2": "string"
        },
        "host": "string",
        "method": "head",
        "params": {
          "additionalProperty1": "string",
          "additionalProperty2": "string"
        },
        "path": "string",
        "port": 42.0,
        "proxy": {
          "host": "string",
          "port": 42.0
        },
        "read_timeout": "string",
        "scheme": "http",
        "url": "string"
      },
      "transform": {
        "chain": [
          {}
        ],
        "script": {
          "lang": "string",
          "params": {
            "additionalProperty1": {},
            "additionalProperty2": {}
          },
          "source": "string",
          "id": "string"
        },
        "search": {
          "request": {
            "body": {
              "query": {}
            },
            "indices": [
              "string"
            ],
            "indices_options": {
              "allow_no_indices": true,
              "expand_wildcards": "string",
              "ignore_unavailable": true,
              "ignore_throttled": true
            },
            "search_type": "query_then_fetch",
            "template": {
              "explain": true,
              "id": "string",
              "params": {},
              "profile": true,
              "source": "string"
            },
            "rest_total_hits_as_int": true
          },
          "timeout": "string"
        }
      },
      "index": {
        "index": "string",
        "doc_id": "string",
        "refresh": "true",
        "op_type": "index",
        "timeout": "string",
        "execution_time_field": "string"
      },
      "logging": {
        "level": "string",
        "text": "string",
        "category": "string"
      },
      "slack": {
        "account": "string",
        "message": {
          "attachments": [
            {
              "author_icon": "string",
              "author_link": "string",
              "author_name": "string",
              "color": "string",
              "fallback": "string",
              "fields": [
                {}
              ],
              "footer": "string",
              "footer_icon": "string",
              "image_url": "string",
              "pretext": "string",
              "text": "string",
              "thumb_url": "string",
              "title": "string",
              "title_link": "string"
            }
          ],
          "dynamic_attachments": {
            "attachment_template": {
              "author_icon": "string",
              "author_link": "string",
              "author_name": "string",
              "color": "string",
              "fallback": "string",
              "fields": [
                {}
              ],
              "footer": "string",
              "footer_icon": "string",
              "image_url": "string",
              "pretext": "string",
              "text": "string",
              "thumb_url": "string",
              "title": "string",
              "title_link": "string"
            },
            "list_path": "string"
          },
          "from": "string",
          "icon": "string",
          "text": "string",
          "to": [
            "string"
          ]
        }
      }
    }
  },
  "condition": {
    "always": {},
    "array_compare": {
      "additionalProperty1": {
        "path": "string"
      },
      "additionalProperty2": {
        "path": "string"
      }
    },
    "compare": {
      "additionalProperty1": {},
      "additionalProperty2": {}
    },
    "never": {},
    "script": {
      "lang": "string",
      "params": {
        "additionalProperty1": {},
        "additionalProperty2": {}
      },
      "source": "string",
      "id": "string"
    }
  },
  "input": {
    "chain": {
      "inputs": [
        {
          "*": {}
        }
      ]
    },
    "http": {
      "extract": [
        "string"
      ],
      "request": {
        "auth": {
          "basic": {
            "password": "string",
            "username": "string"
          }
        },
        "body": "string",
        "connection_timeout": "string",
        "headers": {
          "additionalProperty1": "string",
          "additionalProperty2": "string"
        },
        "host": "string",
        "method": "head",
        "params": {
          "additionalProperty1": "string",
          "additionalProperty2": "string"
        },
        "path": "string",
        "port": 42.0,
        "proxy": {
          "host": "string",
          "port": 42.0
        },
        "read_timeout": "string",
        "scheme": "http",
        "url": "string"
      },
      "response_content_type": "json"
    },
    "search": {
      "extract": [
        "string"
      ],
      "request": {
        "body": {
          "query": {}
        },
        "indices": [
          "string"
        ],
        "indices_options": {
          "allow_no_indices": true,
          "expand_wildcards": "string",
          "ignore_unavailable": true,
          "ignore_throttled": true
        },
        "search_type": "query_then_fetch",
        "template": {
          "explain": true,
          "id": "string",
          "params": {
            "additionalProperty1": {},
            "additionalProperty2": {}
          },
          "profile": true,
          "source": "string"
        },
        "rest_total_hits_as_int": true
      },
      "timeout": "string"
    },
    "simple": {
      "additionalProperty1": {},
      "additionalProperty2": {}
    }
  },
  "metadata": {
    "additionalProperty1": {},
    "additionalProperty2": {}
  },
  "throttle_period": "string",
  "transform": {
    "chain": [
      {}
    ],
    "script": {
      "lang": "string",
      "params": {
        "additionalProperty1": {},
        "additionalProperty2": {}
      },
      "source": "string",
      "id": "string"
    },
    "search": {
      "request": {
        "body": {
          "query": {}
        },
        "indices": [
          "string"
        ],
        "indices_options": {
          "allow_no_indices": true,
          "expand_wildcards": "string",
          "ignore_unavailable": true,
          "ignore_throttled": true
        },
        "search_type": "query_then_fetch",
        "template": {
          "explain": true,
          "id": "string",
          "params": {
            "additionalProperty1": {},
            "additionalProperty2": {}
          },
          "profile": true,
          "source": "string"
        },
        "rest_total_hits_as_int": true
      },
      "timeout": "string"
    }
  },
  "trigger": {
    "schedule": {
      "timezone": "string",
      "cron": "string",
      "daily": {
        "at": [
          "string"
        ]
      },
      "hourly": {
        "minute": [
          42.0
        ]
      },
      "interval": "string",
      "monthly": {
        "at": [
          "string"
        ],
        "on": [
          42.0
        ]
      },
      "weekly": {
        "at": [
          "string"
        ],
        "on": [
          "sunday"
        ]
      },
      "yearly": {
        "at": [
          "string"
        ],
        "int": [
          "january"
        ],
        "on": [
          42.0
        ]
      }
    }
  }
}
Response examples (200)
{
  "created": true,
  "_id": "string",
  "_primary_term": 42.0,
  "_seq_no": 42.0,
  "_version": 42.0
}