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

# Destinations API

Configure, inspect, update and test notification destinations through the connected-apps API.

Destinations are exposed by the API as **connected apps**. Create a destination, use its returned ID in a [notification route](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/notification-routes-api.md), then test delivery. See [Destinations](https://docs.groundcover.com/automate/connected-apps.md) for provider setup. Notification routes and destinations require a BYOC deployment.

## Authentication and permissions

Use an [API key](https://docs.groundcover.com/administer/api-keys.md) with the permissions described below. Include `Authorization: Bearer <YOUR_API_KEY>` and `X-Backend-Id: <YOUR_BACKEND_ID>` on every request; JSON bodies also require `Content-Type: application/json`. Self-hosted deployments use their own API URL.

**Create, update, delete and test require Admin permissions.** Listing and retrieving destinations require Viewer permissions or higher.

The examples use these shell variables:

```bash
export GC_BASE_URL='https://api.groundcover.com'
export GC_API_KEY='<YOUR_API_KEY>'
export GC_BACKEND_ID='<YOUR_BACKEND_ID>'
```

Backend compatibility is selected from `X-Backend-Id`; no API-version header is needed.

## Create a destination

Requires **Admin** permissions.

**POST** `/api/connected-apps/v1`

All three fields are required: `name` (1–255 characters), `type`, and provider-specific `data`.

```bash
curl --fail-with-body -sS -X POST "$GC_BASE_URL/api/connected-apps/v1" \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "X-Backend-Id: $GC_BACKEND_ID" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Production Slack","type":"slack-webhook","data":{"url":"<SLACK_INCOMING_WEBHOOK_URL>"}}'
```

Replace the URL placeholder with a webhook configured in Slack. Returns **201 Created** with `id`, `type` and `data_hash` (a hash of the stored configuration, including secret fields).

### Provider data

| `type`          | Required fields in `data` | Optional fields                                                                       |
| --------------- | ------------------------- | ------------------------------------------------------------------------------------- |
| `slack-webhook` | `url`                     | —                                                                                     |
| `pagerduty`     | `routing_key`             | `severity_mapping`                                                                    |
| `opsgenie`      | `api_key`                 | `region` (`us` or `eu`), `severity_mapping`, `tags`                                   |
| `incidentio`    | `url`                     | `severity_mapping`                                                                    |
| `rootly`        | `api_key`                 | `webhook_url`                                                                         |
| `ms-teams`      | `url`                     | —                                                                                     |
| `webhook`       | `url`                     | `method`, `headers`, `auth_type`, `username`, `password`, `api_key`, `custom_payload` |

Slack App (`slack-app`) and Linear (`linear`) destinations are system-managed by their connectors. Set up those connectors, then list their destinations and reference them from notification routes; do not create them with the generic create endpoint.

`severity_mapping` maps groundcover severity names to provider values. OpsGenie priorities are `P1` through `P5`; OpsGenie `tags` allows up to 20 unique, nonempty strings of at most 50 characters each, with no leading/trailing whitespace.

For a generic `webhook`, `method` defaults to `POST` and accepts `GET`, `POST`, `PUT` or `DELETE`. `auth_type` is empty for no built-in authentication, `basic` (requires `username` and `password`), or `bearer` (requires `api_key`). A `custom_payload` is a JSON template **string**; see [predefined variables](https://docs.groundcover.com/automate/connected-apps/generic-webhook/using-predefined-variables.md).

Example generic webhook request body:

```json
{
  "name": "Operations webhook",
  "type": "webhook",
  "data": {
    "url": "https://alerts.example.com/events",
    "method": "POST",
    "auth_type": "bearer",
    "api_key": "<DESTINATION_BEARER_TOKEN>",
    "headers": {"Content-Type": "application/json"}
  }
}
```

## List and retrieve destinations

Requires **Viewer** permissions or higher.

**POST** `/api/connected-apps/v1/list` takes `{}` or an optional gcQL `query`. It supports name free text, `type:<type>`, and `notification_route:<route-name>`.

```bash
curl --fail-with-body -sS -X POST "$GC_BASE_URL/api/connected-apps/v1/list" \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "X-Backend-Id: $GC_BACKEND_ID" \
  -H 'Content-Type: application/json' \
  -d '{"query":"type:slack-webhook"}'
```

Returns **200** with a `connectedApps` array containing destination IDs, names, types, hashes, creation metadata and `used_by` references.

**GET** `/api/connected-apps/v1/{id}` returns destination metadata and non-secret configuration:

```bash
export DESTINATION_ID='<DESTINATION_ID>'
curl --fail-with-body -sS "$GC_BASE_URL/api/connected-apps/v1/$DESTINATION_ID" \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "X-Backend-Id: $GC_BACKEND_ID"
```

Secret fields, such as webhook credentials, routing keys and Slack incoming webhook URLs, are not returned. Preserve your original configuration if you need to recreate a destination.

## Update a destination

Requires **Admin** permissions.

**PUT** `/api/connected-apps/v1/{id}` requires `name`, `type` and `data`, and returns **200** with the updated destination. Send the complete desired non-secret configuration. Empty or omitted secret fields are filled from the stored destination when updating the same provider type; non-secret fields do not have this preservation behavior.

For example, rename an existing Slack webhook destination while retaining its stored URL:

```bash
curl --fail-with-body -sS -X PUT "$GC_BASE_URL/api/connected-apps/v1/$DESTINATION_ID" \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "X-Backend-Id: $GC_BACKEND_ID" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Production notifications","type":"slack-webhook","data":{}}'
```

## Test a destination

Requires **Admin** permissions.

**POST** `/api/connected-apps/v1/test` sends a real test notification. Required fields are `type` and `data`; optional fields are `name` and `connected_app_id`. To test a new unsaved destination, supply its full provider data. For an existing destination, `connected_app_id` allows empty secret fields to reuse stored secrets; supply all required non-secret fields yourself.

```bash
curl --fail-with-body -sS -X POST "$GC_BASE_URL/api/connected-apps/v1/test" \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "X-Backend-Id: $GC_BACKEND_ID" \
  -H 'Content-Type: application/json' \
  -d "{\"connected_app_id\":\"$DESTINATION_ID\",\"name\":\"Production notifications\",\"type\":\"slack-webhook\",\"data\":{}}"
```

The test response reports `success` and an optional `message`; inspect the HTTP status and body for delivery failures. The destination ID must refer to the same type as the request.

## Delete a destination

Requires **Admin** permissions.

**DELETE** `/api/connected-apps/v1/{id}` returns **204 No Content**. Update referencing notification routes before removing a destination.

```bash
curl --fail-with-body -sS -X DELETE "$GC_BASE_URL/api/connected-apps/v1/$DESTINATION_ID" \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "X-Backend-Id: $GC_BACKEND_ID"
```

Malformed provider data returns **400**; missing destinations return **404**; name conflicts return **409**. System-managed destinations must be managed through their connectors.


---

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