> 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/silences-api.md).

# Silences API

List, retrieve, update, and manage one-time and recurring silences through the unified API.

### Authentication

Use an [API key](https://docs.groundcover.com/administer/api-keys.md) with at least Viewer (`read`) permissions for reads and Editor (`write`) permissions for writes. Include `Authorization: Bearer <YOUR_API_KEY>` and `X-Backend-Id: <YOUR_BACKEND_ID>`. JSON requests require `Content-Type: application/json`.

The examples use `https://api.groundcover.com`. Self-hosted installations use their own API URL and an API key issued in that environment.

### One-time Silence Operations

The existing [Create Silence](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/create-silence.md) and [Delete Silence](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/delete-silence.md) examples cover creation and deletion. Additional operations are:

* **GET** `/api/monitors/silences` lists one-time silences.
* **GET** `/api/monitors/silences/{id}` retrieves one silence.
* **PUT** `/api/monitors/silences/{id}` updates a silence.

List query parameters are `active` (only active windows when true), `includeRecurring` (include one-time instances generated by recurring rules), `limit`, and `skip`. With `active=false`, both active and inactive windows can be returned. The response is an array; increment `skip` until a page has fewer than `limit` entries.

```bash
curl --request GET 'https://api.groundcover.com/api/monitors/silences?active=true&includeRecurring=true&limit=20&skip=0' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>'
```

Get returns the same silence object as create: `id`, `startsAt`, `endsAt`, `comment`, `matchers`, creator fields, and `active`. Generated instances can also have `recurringSilenceId`.

For an update, send the complete desired window, comment, and matchers; omitted fields are not a partial patch:

```bash
curl --request PUT 'https://api.groundcover.com/api/monitors/silences/00000000-0000-4000-8000-000000000001' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "startsAt": "2026-11-01T01:00:00Z",
  "endsAt": "2026-11-01T03:00:00Z",
  "comment": "Planned maintenance",
  "matchers": [
    {
      "name": "team",
      "value": "platform",
      "isRegex": false,
      "isEqual": true
    }
  ]
}'
```

Choose future timestamps for your maintenance window. Success returns HTTP `200` and the updated object.

### Unified Silence Endpoints

Use `/api/monitors/v2/silences` to manage one-time and recurring rules through one API. These routes require a backend that supports unified silences; unsupported backends return `404`.

| Method | Path                             | Result                                       |
| ------ | -------------------------------- | -------------------------------------------- |
| POST   | `/api/monitors/v2/silences`      | Create; HTTP `200` with the created object   |
| GET    | `/api/monitors/v2/silences`      | List; HTTP `200` with `silences` and `done`  |
| GET    | `/api/monitors/v2/silences/{id}` | Get; HTTP `200` with one object              |
| PUT    | `/api/monitors/v2/silences/{id}` | Update; HTTP `200` with the resulting object |
| DELETE | `/api/monitors/v2/silences/{id}` | Delete; HTTP `200` with no body              |

### Create a Unified Silence

All creates require `type` (`one_time` or `recurring`) and non-empty `matchers`; `comment` is optional.

* `one_time` requires `startsAt` and `endsAt` in RFC3339 format.
* `recurring` requires `recurrenceType`, `timeframes`, and an IANA `timezone`; optional `enabled` defaults to true.

Matchers use `name`, `value`, `isEqual` (default true), and `isRegex` (default false). Despite its name, `isRegex: true` enables `*` wildcard matching, not arbitrary regular expressions. See [Create Silence](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/create-silence.md#matcher-object).

```bash
curl --request POST 'https://api.groundcover.com/api/monitors/v2/silences' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "recurring",
  "comment": "Weekly maintenance",
  "matchers": [
    {
      "name": "team",
      "value": "platform",
      "isEqual": true
    }
  ],
  "recurrenceType": "weekly",
  "timeframes": {
    "sunday": [
      {
        "startTime": "01:00",
        "endTime": "03:00"
      }
    ]
  },
  "timezone": "UTC",
  "enabled": true
}'
```

The response has `id`, `type`, `comment`, `matchers`, creator information and timestamps. One-time objects add `startsAt`, `endsAt`, and `active`; recurring objects add `recurrenceType`, `timeframes`, `timezone`, and `enabled`.

### List and Paginate

```bash
curl --request GET 'https://api.groundcover.com/api/monitors/v2/silences?type=recurring&active=true&limit=20&skip=0' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>'
```

Omit `type` to return both kinds. `active=true` selects active one-time windows and enabled recurring rules. `includeRecurring=true` includes the generated one-time instances; it does not control whether recurring rules are listed. Increase `skip` by the page size while `done` is false. `limit` and `skip` must be nonnegative; omitting or setting `limit` to zero selects the default page size.

### Update, Disable, or Convert

Unlike the one-time API, unified PUT updates only supplied fields. Disable a recurring rule without deleting it:

```bash
curl --request PUT 'https://api.groundcover.com/api/monitors/v2/silences/00000000-0000-4000-8000-000000000001' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "enabled": false
}'
```

To change the kind, set `type` to the other kind and supply its required fields. Conversion creates a replacement object and removes the old one: save the **returned `id`**, which changes. When changing recurrence cadence, send `recurrenceType` and the matching `timeframes` together.

### Recurrence Rules

* `daily`: use the `every_day` key.
* `weekly`: use lowercase weekday names, such as `monday`.
* Times are `HH:MM` in the supplied timezone. Split windows crossing midnight across the appropriate days, as shown in the recurring-silence examples. Use `00:00` to `00:00` for a full-day window.

See [Recurring Silences API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/recurring-silences-api.md) for the dedicated recurring-rule endpoints and additional examples.


---

# 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/silences-api.md?ask=<question>&goal=<user_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.
