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.

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)

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.

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:

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

{
  "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": "[e-mail]",
  "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:

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:

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

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

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:

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

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 documentation for more details on how recurring silences work.