> 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](/reference/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` | 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" %} 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 | 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). Since overnight windows must be split, this uses two days: ```bash curl -sS -X POST 'https://api.groundcover.com/api/monitors/recurring-silences' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -H 'X-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://api.groundcover.com/api/monitors/recurring-silences' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -H 'X-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 ' \ -H 'Content-Type: application/json' \ -H 'X-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 ' \ -H 'X-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/' \ -H 'Authorization: Bearer ' \ -H 'X-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/' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -H 'X-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/' \ -H 'Authorization: Bearer ' \ -H 'X-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](/automate/monitors/silences-page.md) documentation for more details on how recurring silences work. --- # 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=&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.