# Create Silence

{% hint style="info" %}
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](/use-groundcover/remote-access-and-apis/api-examples/recurring-silences-api.md).
{% endhint %}

### 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`  | Yes      | 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       | 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 7-day silence for all monitors with label `team=tam`:

```bash
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://app.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
      }
    ]
  }"
```

{% hint style="info" %}
On **macOS**, replace the `END=` line with:\
`END=$(date -u -v+7d +%Y-%m-%dT%H:%M:%SZ)`
{% endhint %}

### Response

#### Success Response

**Status Code:** `200 OK`

```json
{
  "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](/use-groundcover/monitors/silences-page.md) documentation for more details on how matchers 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/create-silence.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.