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

# Synthetics API

Create and manage synthetic checks and their associated monitors.

### Authentication and permissions

Use an [API key](https://docs.groundcover.com/administer/api-keys.md) in `Authorization: Bearer <YOUR_API_KEY>` and select the backend with `X-Backend-Id: <YOUR_BACKEND_ID>`. Use your own API base URL for a self-hosted deployment.

Creating, updating and deleting synthetic checks require **Editor or Admin** permissions. Listing and reading checks require access to the backend.

### Endpoints

| Method | Endpoint                        | Purpose                                    |
| ------ | ------------------------------- | ------------------------------------------ |
| GET    | `/api/synthetics/v1/rules`      | List synthetic checks and status.          |
| POST   | `/api/synthetics/v1/rules`      | Create a check.                            |
| GET    | `/api/synthetics/v1/rules/{id}` | Retrieve its full configuration.           |
| PUT    | `/api/synthetics/v1/rules/{id}` | Replace its configuration.                 |
| DELETE | `/api/synthetics/v1/rules/{id}` | Delete a check and its associated monitor. |

### Create a check

This example creates an HTTP check without an associated monitor. Replace the URL with an endpoint reachable from your backend.

```bash
curl --request POST 'https://api.groundcover.com/api/synthetics/v1/rules' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "version": 1,
  "name": "example-healthcheck",
  "enabled": true,
  "interval": "1m",
  "createMonitor": false,
  "checkConfig": {
    "kind": "http",
    "metadata": {
      "syntheticName": "example-healthcheck"
    },
    "request": {
      "http": {
        "kind": "http",
        "url": "https://example.com/",
        "method": "GET",
        "timeout": "10s"
      }
    },
    "executionPolicy": {
      "assertions": [
        {"source": "statusCode", "operator": "eq", "target": "200"}
      ]
    },
    "tracing": {
      "forceSampling": false
    }
  }
}'
```

| Field                         | Description                                                                   |
| ----------------------------- | ----------------------------------------------------------------------------- |
| `version`                     | Configuration-schema version; use `1`. This is not a software release number. |
| `name`                        | Name of the check.                                                            |
| `enabled`                     | Whether the check is enabled.                                                 |
| `interval`                    | Check interval as a duration, between 15 seconds and 1 hour.                  |
| `checkConfig.kind`            | Check type. HTTP, SSL, TCP and DNS checks have type-specific request blocks.  |
| `checkConfig.request`         | Request block matching the chosen kind (`http`, `ssl`, `tcp`, or `dns`).      |
| `checkConfig.executionPolicy` | Assertions and optional retry count/interval.                                 |
| `createMonitor`               | Controls creation or removal of an associated monitor; see below.             |
| `monitor`                     | Optional associated monitor configuration.                                    |

Assertions select a `source`, an `operator`, and, when required, a string `target`. For example, `statusCode` with `eq` and `"200"` checks the HTTP response status. Supported combinations depend on the check kind.

The check interval must exceed the complete timeout budget, including retries. An HTTP request needs `kind`, `url`, `method`, and `timeout`; other check types use their own fields.

Get current check capabilities and configuration options with:

```bash
curl --request GET 'https://api.groundcover.com/api/integrations/v1/data/describe/synthetics' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>'
```

Creating returns HTTP 201 with `{"id":"<SYNTHETIC_ID>"}`. Invalid checks return HTTP 400; a conflicting name can return HTTP 409.

### Read and update

```bash
curl --request GET 'https://api.groundcover.com/api/synthetics/v1/rules' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>'
```

```bash
curl --request GET 'https://api.groundcover.com/api/synthetics/v1/rules/<SYNTHETIC_ID>' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>'
```

The list response is `{"synthetics":[...]}` with ID, name, type, target, status, creator, interval, modified time and available last-check information. When a monitor exists, `monitor.uuid` identifies it.

GET by ID returns the check configuration, with `monitor` when present. Edit that configuration, save the complete request as `synthetic-request.json`, and PUT it:

```bash
curl --request PUT 'https://api.groundcover.com/api/synthetics/v1/rules/<SYNTHETIC_ID>'   --header 'Authorization: Bearer <YOUR_API_KEY>'   --header 'X-Backend-Id: <YOUR_BACKEND_ID>'   --header 'Content-Type: application/json'   --data-binary @synthetic-request.json
```

PUT returns HTTP 200 with `{}`. A missing ID returns HTTP 404.

### Associated monitor behavior

* On create, omitting `createMonitor` or setting it to `true` creates a monitor. Set it to `false` to skip monitor creation.
* On update, omitting `createMonitor` preserves whether a monitor exists. Setting it to `true` creates or keeps a monitor; setting it to `false` deletes the associated monitor.
* If the check has no monitor, explicitly set `createMonitor: true` before supplying a `monitor` configuration. A `monitor` block with `createMonitor: false` is invalid.
* The synthetic service generates the monitor query; a supplied `monitor.query` is not used.

Optional `monitor` fields include `monitor_name`, `issue_summary`, `issue_description`, `severity`, `noDataState`, `executionErrorState`, `evaluationInterval` (`interval` and `pendingFor`), and `lookbehind_window`.

For notifications, `monitor.notificationMethod` accepts `notificationRoutes` (default), `connectedApps`, or `noNotifications`. Direct delivery uses `connectedApps` (destination IDs), optional `connectedAppParams` keyed by those IDs, and `statusFilters`. `renotificationInterval` and `disableRenotification` control repeated notifications. These fields configure the associated monitor; they are not fields of `checkConfig`.

### Delete

```bash
curl --request DELETE 'https://api.groundcover.com/api/synthetics/v1/rules/<SYNTHETIC_ID>' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>'
```

Successful deletion returns HTTP 204 with no body.

See [Synthetics](https://docs.groundcover.com/investigate/synthetics.md) for configuring checks in the UI.


---

# 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/synthetics-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.
