elasticsearch/docs/reference/rest-api/watcher/delete-watch.asciidoc

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

.New API reference
[sidebar]
--
For the most up-to-date API details, refer to {api-es}/group/endpoint-watcher[{watcher} APIs].
--

Removes a watch from {watcher}.

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

`DELETE _watcher/watch/<watch_id>`

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

* You must have `manage_watcher` cluster privileges to use this API. For more
information, see <<security-privileges>>.

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

When the watch is removed, the document representing the watch in the `.watches`
index is gone and it will never be run again.

Please note that deleting a watch **does not** delete any watch execution records
related to this watch from the watch history.

IMPORTANT:  Deleting a watch must be done via this API only. Do not delete the
            watch directly from the `.watches` index using the Elasticsearch
            DELETE Document API. When {es} {security-features} are enabled, make
            sure no `write` privileges are granted to anyone over the `.watches`
            index.

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

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

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

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

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

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

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

The following example deletes a watch with the `my-watch` id:

[source,console]
--------------------------------------------------
DELETE _watcher/watch/my_watch
--------------------------------------------------
// TEST[setup:my_active_watch]

Response:

[source,console-result]
--------------------------------------------------
{
   "found": true,
   "_id": "my_watch",
   "_version": 2
}
--------------------------------------------------