# Recurring Silences API

Recurring silences automatically create time-bounded silence instances on a repeating schedule (daily or weekly). For one-time silences with a fixed start and end time, see [Create Silence](/use-groundcover/remote-access-and-apis/api-examples/create-silence.md).

## Create a Recurring Silence

### Endpoint

**POST** `/api/monitors/recurring-silences`

### Authentication

This endpoint requires API Key authentication via the Authorization header.

### Headers

| Header          | Required | Description                                                  |
| --------------- | -------- | ------------------------------------------------------------ |
| `Authorization` | Yes      | Bearer token with your API key                               |
| `Content-Type`  | Yes      | Must be `application/json`                                   |
| `X-Backend-Id`  | Yes      | Your Backend ID, to route the request to the correct backend |

### Request Body

| Field            | Type   | Required | Description                                                           |
| ---------------- | ------ | -------- | --------------------------------------------------------------------- |
| `recurrenceType` | string | Yes      | `daily` or `weekly`                                                   |
| `timeframes`     | object | Yes      | Map of timeframe keys to arrays of time ranges (see below)            |
| `timezone`       | string | Yes      | IANA timezone name (e.g. `America/New_York`, `UTC`, `Asia/Jerusalem`) |
| `matchers`       | array  | Yes      | List of label matchers to select which monitors to silence            |
| `comment`        | string | No       | A note describing the reason for the recurring silence                |

#### Timeframe Keys

The keys in the `timeframes` object depend on the `recurrenceType`:

| Recurrence type | Allowed keys                                                                 |
| --------------- | ---------------------------------------------------------------------------- |
| `daily`         | `every_day`                                                                  |
| `weekly`        | `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday` |

Each key maps to an array of time range objects:

| Field       | Type   | Required | Description                        |
| ----------- | ------ | -------- | ---------------------------------- |
| `startTime` | string | Yes      | Start time in `HH:MM` format (24h) |
| `endTime`   | string | Yes      | End time in `HH:MM` format (24h)   |

{% hint style="info" %}
The `startTime` must be less than the `endTime` in each time range. Overnight windows are not supported as a single range — split them into two ranges instead. For example, to cover 10 PM to 6 AM, use `22:00–00:00` and `00:00–06:00` as separate entries. The one exception is `00:00` to `00:00`, which represents a full day.
{% endhint %}

#### Matcher Object

| Field     | Type    | Required | Description                                                                      |
| --------- | ------- | -------- | -------------------------------------------------------------------------------- |
| `name`    | string  | Yes      | Label name to match (e.g. `cluster`, `namespace`, `alertname`)                   |
| `value`   | string  | Yes      | Label value to match                                                             |
| `isRegex` | boolean | No       | Whether `value` is a regular expression (defaults to `false`)                    |
| `isEqual` | boolean | No       | Whether the match is equality (`true`) or negation (`false`, defaults to `true`) |

### Example Request

Create a weekly recurring silence that suppresses all alerts in the `production` cluster every Sunday 10 PM to Monday 6 AM (New York time). Since overnight windows must be split, this uses two days:

```bash
curl -sS -X POST 'https://app.groundcover.com/api/monitors/recurring-silences' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  -d '{
    "recurrenceType": "weekly",
    "timeframes": {
      "monday": [{"startTime": "00:00", "endTime": "06:00"}],
      "sunday": [{"startTime": "22:00", "endTime": "00:00"}]
    },
    "timezone": "America/New_York",
    "matchers": [
      {
        "name": "cluster",
        "value": "production",
        "isRegex": false,
        "isEqual": true
      }
    ],
    "comment": "Weekly Sunday maintenance window"
  }'
```

### Response

**Status Code:** `200 OK`

```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "comment": "Weekly Sunday maintenance window",
  "matchers": [
    {
      "name": "cluster",
      "value": "production",
      "isRegex": false,
      "isEqual": true
    }
  ],
  "recurrenceType": "weekly",
  "timeframes": {
    "monday": [{"startTime": "00:00", "endTime": "06:00"}],
    "sunday": [{"startTime": "22:00", "endTime": "00:00"}]
  },
  "timezone": "America/New_York",
  "createdBy": "user-123",
  "createdByEmail": "user@example.com",
  "createdAt": "2025-07-01T10:30:00Z",
  "updatedAt": "2025-07-01T10:30:00Z"
}
```

### More Examples

#### Daily nightly silence (overnight split)

Silence every night from 8 PM to 8 AM. Since overnight windows must be split, this uses two time ranges:

```bash
curl -sS -X POST 'https://app.groundcover.com/api/monitors/recurring-silences' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  -d '{
    "recurrenceType": "daily",
    "timeframes": {
      "every_day": [
        {"startTime": "20:00", "endTime": "00:00"},
        {"startTime": "00:00", "endTime": "08:00"}
      ]
    },
    "timezone": "UTC",
    "matchers": [
      {
        "name": "namespace",
        "value": "etl",
        "isRegex": false,
        "isEqual": true
      }
    ],
    "comment": "Nightly ETL window"
  }'
```

#### Weekend all-day silence

Silence non-critical alerts for the entire weekend. Use `00:00` to `00:00` for a full-day window:

```bash
curl -sS -X POST 'https://app.groundcover.com/api/monitors/recurring-silences' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  -d '{
    "recurrenceType": "weekly",
    "timeframes": {
      "saturday": [{"startTime": "00:00", "endTime": "00:00"}],
      "sunday":   [{"startTime": "00:00", "endTime": "00:00"}]
    },
    "timezone": "Asia/Jerusalem",
    "matchers": [
      {
        "name": "severity",
        "value": "S4",
        "isRegex": false,
        "isEqual": true
      }
    ],
    "comment": "Suppress low-severity alerts on weekends"
  }'
```

***

## List Recurring Silences

### Endpoint

**GET** `/api/monitors/recurring-silences`

### Query Parameters

| Parameter | Type    | Required | Description                                |
| --------- | ------- | -------- | ------------------------------------------ |
| `limit`   | integer | No       | Maximum number of results to return        |
| `skip`    | integer | No       | Number of results to skip (for pagination) |

### Example Request

```bash
curl -sS -X GET 'https://app.groundcover.com/api/monitors/recurring-silences?limit=10' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'X-Backend-Id: <YOUR_BACKEND_ID>'
```

### Response

**Status Code:** `200 OK`

Returns an array of recurring silence objects.

***

## Get a Recurring Silence

### Endpoint

**GET** `/api/monitors/recurring-silences/{id}`

### Path Parameters

| Parameter | Type   | Required | Description                       |
| --------- | ------ | -------- | --------------------------------- |
| `id`      | string | Yes      | The UUID of the recurring silence |

### Example Request

```bash
curl -sS -X GET 'https://app.groundcover.com/api/monitors/recurring-silences/<RECURRING_SILENCE_ID>' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'X-Backend-Id: <YOUR_BACKEND_ID>'
```

### Response

**Status Code:** `200 OK`

Returns a single recurring silence object (same shape as the create response).

***

## Update a Recurring Silence

### Endpoint

**PUT** `/api/monitors/recurring-silences/{id}`

### Path Parameters

| Parameter | Type   | Required | Description                       |
| --------- | ------ | -------- | --------------------------------- |
| `id`      | string | Yes      | The UUID of the recurring silence |

### Request Body

All fields are optional — only include the fields you want to update. Omitted fields remain unchanged.

| Field            | Type   | Description                                    |
| ---------------- | ------ | ---------------------------------------------- |
| `recurrenceType` | string | `daily` or `weekly`                            |
| `timeframes`     | object | Map of timeframe keys to arrays of time ranges |
| `timezone`       | string | IANA timezone name                             |
| `matchers`       | array  | List of label matchers                         |
| `comment`        | string | Description of the recurring silence           |

### Example Request

Update the comment on an existing recurring silence:

```bash
curl -sS -X PUT 'https://app.groundcover.com/api/monitors/recurring-silences/<RECURRING_SILENCE_ID>' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  -d '{
    "comment": "Updated maintenance window description"
  }'
```

### Response

**Status Code:** `200 OK`

Returns the updated recurring silence object.

***

## Delete a Recurring Silence

### Endpoint

**DELETE** `/api/monitors/recurring-silences/{id}`

### Path Parameters

| Parameter | Type   | Required | Description                       |
| --------- | ------ | -------- | --------------------------------- |
| `id`      | string | Yes      | The UUID of the recurring silence |

### Example Request

```bash
curl -sS -X DELETE 'https://app.groundcover.com/api/monitors/recurring-silences/<RECURRING_SILENCE_ID>' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'X-Backend-Id: <YOUR_BACKEND_ID>'
```

### Response

**Status Code:** `200 OK`

### Notes

* Deleting a recurring silence also removes any future silence instances that haven't started yet.
* Active silence instances that are currently in effect are not affected by the deletion.
* See the [Silences page](/use-groundcover/monitors/silences-page.md) documentation for more details on how recurring silences work.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.groundcover.com/use-groundcover/remote-access-and-apis/api-examples/recurring-silences-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.