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

# Notification Routes API

Create and manage notification routes, and preview which routes match a monitor.

[Notification routes](https://docs.groundcover.com/automate/monitors/notification-routes.md) match monitor issues and deliver notifications through [Destinations](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/destinations-api.md). Configure a destination first, then use its returned `id` and `type` in a route. This capability is available for BYOC deployments.

## Authentication

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.

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>'
```

Viewer permissions allow list, get and preview. Creating, updating and deleting routes requires Editor permissions or higher. Backend capability selection is automatic; send `X-Backend-Id` rather than an API-version header.

## Create a route

**POST** `/api/notification-routes/v1`

| Field                                         | Required    | Description                                                                                                   |
| --------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------- |
| `name`                                        | Yes         | Route name, 1–255 characters.                                                                                 |
| `query`                                       | Yes         | gcQL condition matching issue labels and monitor metadata.                                                    |
| `routes`                                      | Yes         | Nonempty array of status/destination rules.                                                                   |
| `routes[].status`                             | Yes         | Nonempty array containing `Alerting`, `Resolved`, or both. The API uses `Alerting` for the UI's Firing state. |
| `routes[].connectedApps`                      | Yes         | Nonempty array of destination references. Each needs `type` and `id`.                                         |
| `routes[].connectedApps[].params`             | Conditional | Route-specific settings for Slack App and Linear; omit for other destination types.                           |
| `notificationSettings.renotificationInterval` | No          | Duration between repeated firing notifications, for example `30m` or `4h`.                                    |
| `notificationSettings.disableRenotification`  | No          | Set `true` to disable repeat notifications.                                                                   |

Save this as `notification-route.json`, replacing the destination ID with the value returned by the Destinations API:

```json
{
  "name": "Production alerts",
  "query": "env:prod",
  "routes": [
    {
      "status": ["Alerting", "Resolved"],
      "connectedApps": [
        {"type": "slack-webhook", "id": "<DESTINATION_ID>"}
      ]
    }
  ],
  "notificationSettings": {
    "renotificationInterval": "4h",
    "disableRenotification": false
  }
}
```

```bash
curl --fail-with-body -sS -X POST "$GC_BASE_URL/api/notification-routes/v1" \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "X-Backend-Id: $GC_BACKEND_ID" \
  -H 'Content-Type: application/json' \
  --data-binary @notification-route.json
```

Returns **201 Created** with `{"id":"<ROUTE_ID>"}`. Multiple routes can match the same issue. The scope query applies automatically; it does not need to be attached individually to each monitor.

Supported repeat intervals are 1m, 2m, 5m, 10m, 30m, 1h, 2h, 4h, 8h, 12h, 24h and 48h. Use `24h`/`48h` in the API for the UI's 1d/2d options.

### Slack App and Linear parameters

Slack App destinations are created by the Slack connector. Use the destination ID from `/api/connected-apps/v1/list` and select channels per route:

```json
{
  "type": "slack-app",
  "id": "<SLACK_APP_DESTINATION_ID>",
  "params": {
    "channels": [{"id": "<SLACK_CHANNEL_ID>", "name": "#alerts"}]
  }
}
```

At least one channel ID is required; `name` is optional display metadata. For a `linear` destination, `params.team_id` is required. Automatic resolution defaults to enabled and requires `params.resolved_status_id`; set `auto_resolve:false` to disable it. Optional fields include `project_id`, `label_ids`, `assignee_id` and `delegate_id`. See [Linear](https://docs.groundcover.com/automate/connectors/linear.md) for connector setup.

## List and get routes

**POST** `/api/notification-routes/v1/list` accepts `{}` or an optional `query` containing free text to search route names. This is distinct from the issue-matching gcQL `query` in a route definition.

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

Returns **200** with `notificationRoutes`, an array containing IDs, names, scope queries, rules and creation/modification metadata.

**GET** `/api/notification-routes/v1/{id}` returns the complete route, including `notificationSettings`, `createdBy`, `createdAt`, `modifiedBy` and `modifiedAt`. Destination names are resolved in the returned rules.

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

## Update and delete

**PUT** `/api/notification-routes/v1/{id}` accepts the same required fields as create and replaces the route definition. Edit `notification-route.json` and submit the complete desired configuration:

```bash
curl --fail-with-body -sS -X PUT "$GC_BASE_URL/api/notification-routes/v1/$ROUTE_ID" \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "X-Backend-Id: $GC_BACKEND_ID" \
  -H 'Content-Type: application/json' \
  --data-binary @notification-route.json
```

Returns **200** with the updated route. **DELETE** `/api/notification-routes/v1/{id}` removes it and returns **204 No Content**:

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

Invalid rules, queries or parameters return **400**; missing routes return **404** and name conflicts return **409**.

## Preview matching routes

**POST** `/api/notification-routes/v1/search` previews matching routes for a **monitor definition**, not a free-text route-name search. Send the monitor model (`title`, `severity`, `category`, `labels`, and `model.queries`), with optional absolute `start`/`end` RFC3339 timestamps. It evaluates available query series to include grouping labels; if no series are available or query execution fails, it falls back to static monitor metadata.

This example previews a static label match without executing a data query:

```bash
curl --fail-with-body -sS -X POST "$GC_BASE_URL/api/notification-routes/v1/search" \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "X-Backend-Id: $GC_BACKEND_ID" \
  -H 'Content-Type: application/json' \
  -d '{"title":"Service errors","severity":"S2","labels":{"env":"prod"},"model":{"queries":[]}}'
```

Returns **200** with `{"matchingRoutes":[{"id":"<ROUTE_ID>","name":"Production alerts","query":"env:prod"}]}`. A preview does not send notifications and cannot prove that a destination will accept them. Use the [destination test endpoint](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/destinations-api.md#test-a-destination) to test delivery.


---

# 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/notification-routes-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.
