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

# Data Integrations API

Discover configuration options and manage data source integrations.

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

**Admin required:** creating, replacing or archiving integration configurations, and testing connections. Listing, reading and describing configurations require backend access but do not require Admin permissions.

### Endpoints

| Method | Endpoint                                           | Purpose                                                     |
| ------ | -------------------------------------------------- | ----------------------------------------------------------- |
| GET    | `/api/integrations/v1/data/config`                 | List configurations across types.                           |
| GET    | `/api/integrations/v1/data/config/{type}`          | List configurations of one type.                            |
| GET    | `/api/integrations/v1/data/config/{type}/{id}`     | Get one configuration.                                      |
| GET    | `/api/integrations/v1/data/describe/{type}`        | Read configuration defaults, options and supported actions. |
| POST   | `/api/integrations/v1/data/config/{type}`          | **Admin required.** Create a configuration.                 |
| PUT    | `/api/integrations/v1/data/config/{type}/{id}`     | **Admin required.** Replace a configuration.                |
| DELETE | `/api/integrations/v1/data/config/{type}/{id}`     | **Admin required.** Archive a configuration.                |
| POST   | `/api/integrations/v1/data/{type}/test-connection` | **Admin required.** Test supported backend integrations.    |

Use the [Synthetics API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/synthetics-api.md) for synthetic checks. The generic configuration API rejects `synthetics` for create, update, get-by-type, delete and test operations; its describe endpoint remains available.

### Discover and list

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

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

Describe returns `version`, optional `defaults` and `options`, and `supported_actions`. These describe the selected integration type; they are not a universal schema shared by every integration. Read defaults and the corresponding data-source guide before constructing `config`.

List and get accept the optional query parameter `includeArchived=true`. Lists return an array of configuration objects containing `type`, `id`, `name`, `config`, `is_paused`, `is_archived`, `updated_by`, `update_timestamp`, `tags`, and optional `cluster`. `config` is serialized configuration text.

### Create an integration

| Field       | Type    | Required | Description                                                          |
| ----------- | ------- | -------- | -------------------------------------------------------------------- |
| `config`    | string  | Yes      | Type-specific JSON text. Include its configuration-schema `version`. |
| `name`      | string  | No       | Configuration display name.                                          |
| `cluster`   | string  | No       | Cluster scope. Omit for the backend integration scope.               |
| `is_paused` | boolean | No       | Whether the configuration is paused.                                 |
| `tags`      | object  | No       | Metadata attached to the integration configuration.                  |

The example uses the `prometheusscrape` type. Replace the target with a reachable metrics endpoint in your environment.

```bash
curl --request POST 'https://api.groundcover.com/api/integrations/v1/data/config/prometheusscrape' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "example-metrics",
  "config": "{\"version\": 1, \"name\": \"example-metrics\", \"enabled\": true, \"staticTargets\": [\"metrics.example.com:9090\"], \"scheme\": \"https\", \"metricsPath\": \"/metrics\"}",
  "is_paused": false
}'
```

HTTP 201 returns the created configuration, including its server-generated `id`. Use this ID for subsequent operations. Invalid configuration returns HTTP 400; an unavailable configuration service can return HTTP 503.

### Update and delete

PUT accepts the same complete body as POST. Retrieve the existing configuration first, retain its type-specific fields, and change only the intended values in your request. To pause an integration, submit the complete request with `is_paused: true`.

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

Save your edited request body as `integration-request.json` (using the request fields above), then submit it:

```bash
curl --request PUT 'https://api.groundcover.com/api/integrations/v1/data/config/prometheusscrape/<INTEGRATION_ID>'   --header 'Authorization: Bearer <YOUR_API_KEY>'   --header 'X-Backend-Id: <YOUR_BACKEND_ID>'   --header 'Content-Type: application/json'   --data-binary @integration-request.json
```

PUT returns HTTP 200 with the updated configuration. Delete archives the configuration:

```bash
curl --request DELETE 'https://api.groundcover.com/api/integrations/v1/data/config/prometheusscrape/<INTEGRATION_ID>' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>'
```

For a cluster-scoped integration, pass its cluster in the DELETE query string (`?cluster=<CLUSTER_NAME>`). URL-encode the name. Deleting returns HTTP 200 with no body.

### Test a connection

**Admin permissions are required**, even though this operation does not save a configuration.

Send the same request body as create to `/api/integrations/v1/data/{type}/test-connection`. Omit `cluster`: testing is supported only in the backend cluster. Check the describe response for `test-connection` in `supported_actions`; it is not supported by every integration or backend.

```bash
curl --request POST 'https://api.groundcover.com/api/integrations/v1/data/prometheusscrape/test-connection'   --header 'Authorization: Bearer <YOUR_API_KEY>'   --header 'X-Backend-Id: <YOUR_BACKEND_ID>'   --header 'Content-Type: application/json'   --data-binary @integration-request.json
```

The response contains `statusCode`, `status`, and `message`; inspect the result to determine whether the connection succeeded. The test does not create a saved configuration.


---

# 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/data-integrations-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.
