> 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/use-groundcover/remote-access-and-apis/api-examples/create-silence.md).

# 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       | 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`:

```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
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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.groundcover.com/use-groundcover/remote-access-and-apis/api-examples/create-silence.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.