Create Silence

Create a new one-time silence rule to suppress monitor notifications for a specified time period, using label matchers to target specific monitors or issues.

This endpoint creates a one-time silence with a fixed start and end time. To create silences that repeat on a schedule (daily, weekly, or monthly), see Recurring Silences API.

Endpoint

POST /api/monitors/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
startsAt	string	Yes	Silence start time in ISO 8601 format (e.g. 2025-07-01T00:00:00Z)
endsAt	string	Yes	Silence end time in ISO 8601 format (e.g. 2025-07-08T00:00:00Z)
comment	string	No	A note describing the reason for the silence
matchers	array	Yes	List of label matchers to select which monitors to silence

Matcher Object

Field	Type	Required	Description
name	string	Yes	Label name to match (e.g. team, cluster, namespace)
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 7-day silence for all monitors with label team=tam:

START=$(date -u +%Y-%m-%dT%H:%M:%SZ)
END=$(date -u -d '+7 days' +%Y-%m-%dT%H:%M:%SZ)

curl -sS -X POST 'https://api.groundcover.com/api/monitors/silences' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  -d "{
    \"startsAt\": \"$START\",
    \"endsAt\": \"$END\",
    \"comment\": \"API test: team=tam, 7d\",
    \"matchers\": [
      {
        \"name\": \"team\",
        \"value\": \"tam\",
        \"isRegex\": false,
        \"isEqual\": true
      }
    ]
  }"

On macOS, replace the END= line with: END=$(date -u -v+7d +%Y-%m-%dT%H:%M:%SZ)

Response

Success Response

Status Code: 200 OK

{
  "silenceID": "91c9683d-705b-4aea-a988-3edc8ca07060"
}

Notes

• The startsAt value can be in the future to schedule a silence ahead of time.

• Combine multiple matchers in the matchers array to target silences more precisely.

• The returned silenceID is needed to delete the silence later.

• See the Silences page documentation for more details on how matchers work.