rest_api_watch_activate.md 1.97 KB
Newer Older
1
2
3
4
5
6
7
---
title: Activate and deactivate watch
html_title: Activating and deactivating a watch with the REST API
slug: elasticsearch-alerting-rest-api-watch-activate
category: signals-rest
order: 500
layout: docs
8
edition: beta
9
10
11
12
13
description: 
---

<!--- Copyright 2019 floragunn GmbH -->

Nils Bandener's avatar
Nils Bandener committed
14
# Activate/Deactivate Watch API
15
16
17
18
{: .no_toc}

{% include toc.md %}

Nils Bandener's avatar
Nils Bandener committed
19
20
21
22

## Endpoint

```
Nils Bandener's avatar
Nils Bandener committed
23
PUT /_signals/watch/{tenant}/{watch_id}/_active
Nils Bandener's avatar
Nils Bandener committed
24
25
26
```

```
Nils Bandener's avatar
Nils Bandener committed
27
DELETE /_signals/watch/{tenant}/{watch_id}/_active
Nils Bandener's avatar
Nils Bandener committed
28
29
30
31
```

These endpoints can be used to activate and deactivate watches. Inactive watches are not automatically executed.

Nils Bandener's avatar
Nils Bandener committed
32
33
Using the PUT verb activates a watch, using the DELETE verb deactivates a watch.

Nils Bandener's avatar
Nils Bandener committed
34
35
## Path Parameters

Nils Bandener's avatar
Nils Bandener committed
36
37
38
**{tenant}:** The name of the tenant which contains the watch to be activated or deactivated. `_main` refers to the default tenant. Users of the community edition will can only use `_main` here.

**{watch_id}:** The id of the watch to be activated or deactivated. Required.
Nils Bandener's avatar
Nils Bandener committed
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

## Request Body

No request body is required for this endpoint.

## Responses

### 200 OK

A watch identified by the given id exists and was successfully activated or deactivated.

### 403 Forbidden

The user does not have the permission to activate or deactivate watches for the currently selected tenant. 

### 404 Not found

A watch with the given id does not exist for the current tenant.


## Permissions

For being able to access the endpoint, the user needs to have the privilege `cluster:admin:searchguard:tenant:signals:watch/activate_deactivate` for the currently selected tenant.

This permission is distinct for the permission required to create or updated watches. Thus, a user may be allowed to activate or deactivate watches without being allowed to create or update watches.

Jochen Kressin's avatar
Jochen Kressin committed
65
66
67
68
This permission is included in the following [built-in action groups](security_permissions.md):

* SGS\_SIGNALS\_WATCH\_ACTIVATE

Nils Bandener's avatar
Nils Bandener committed
69
70
## Examples

Nils Bandener's avatar
Nils Bandener committed
71
### Deactivate a Watch 
Nils Bandener's avatar
Nils Bandener committed
72
73

```
Nils Bandener's avatar
Nils Bandener committed
74
DELETE /_signals/watch/_main/bad_weather/_active
Nils Bandener's avatar
Nils Bandener committed
75
76
77
78
79
80
81
82
```

**Response**

```
200 OK
```