> For the complete documentation index, see [llms.txt](https://docs.groundcover.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/recurring-silences-api.md).

# Recurring Silences API

Create, list, update, and delete recurring silence rules that automatically suppress monitor notifications on a repeating schedule.

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](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/create-silence.md).

## Create a Recurring Silence

### Endpoint

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

### Authentication

Use API key authentication via the Authorization header. Create, update, and delete require at least Editor (`write`) permissions; get and list require at least Viewer (`read`) permissions.

### Headers

| Header          | Required                        | Description                                                  |
| --------------- | ------------------------------- | ------------------------------------------------------------ |
| `Authorization` | Yes                             | Bearer token with your API key                               |
| `Content-Type`  | Yes                             | Must be `application/json`                                   |
| `X-Backend-Id`  | Only for multi-backend accounts | 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" %}
For a window that crosses midnight, split it into two ranges on the appropriate days. For example, Sunday 10 PM to Monday 6 AM uses Sunday `22:00`–`00:00` and Monday `00:00`–`06:00`. Within a day, put the start before the end; `00:00` can mark the end of that day. Use `00:00` to `00:00` for a full-day window. Times use `HH:MM` with hours 00–23 and minutes 00–59.
{% 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       | When `true`, `value` is treated as a wildcard pattern where `*` matches any sequence of characters (e.g. `*checkout*`). All other characters are matched literally; full regular expressions are not supported. Defaults to `false` (exact match). |
| `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). Split the overnight window across the two days:

```bash
curl -sS -X POST 'https://api.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. Split the overnight window into two ranges:

```bash
curl -sS -X POST 'https://api.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://api.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://api.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://api.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://api.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://api.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](https://docs.groundcover.com/automate/monitors/silences-page.md) documentation for more details on how recurring silences work.

## Enable or Disable a Recurring Silence

`enabled` is optional on creation and defaults to true. Set `{"enabled": false}` with **PUT** `/api/monitors/recurring-silences/{id}` to disable a rule; use true to enable it again. GET responses include `enabled`. The list endpoint accepts `enabledOnly=true` alongside `limit` and `skip`.

A backend without recurring-silence support returns `404`. For a single API covering both one-time and recurring rules, see [Silences API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/silences-api.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
