> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcollate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Alerts

> Manage alerts (event subscriptions) with the Collate REST API and Python SDK, including the request schema for sources, filters, triggers, and destinations.

# Alerts

An **alert** in the Collate UI is an **event subscription** in the API. Use these endpoints to create, update, and delete alerts as code, and to inspect what an alert has delivered.

> [card] [Create an Alert](https://docs.getcollate.io/ai-2-0/developer-guide/api-reference/alerts/create.md)
>
> Create an alert, or create or update it by name, with a source, filters, triggers, and destinations.

> [card] [List and Retrieve Alerts](https://docs.getcollate.io/ai-2-0/developer-guide/api-reference/alerts/list.md)
>
> List alerts, read one, look up available filters and triggers, and inspect delivery status.

> [card] [Update an Alert](https://docs.getcollate.io/ai-2-0/developer-guide/api-reference/alerts/update.md)
>
> Change an alert with JSON Patch or by sending the full definition again.

> [card] [Delete an Alert](https://docs.getcollate.io/ai-2-0/developer-guide/api-reference/alerts/delete.md)
>
> Delete an alert and its delivery records.

For what each source, trigger, and filter does, and when an alert fires, see the [Alert Behavior Reference](https://docs.getcollate.io/ai-2-0/how-to-guides/data-quality-observability/alerts-notifications/alert-behavior-reference.md). For what a webhook receives, see [Webhook Payloads and Delivery](https://docs.getcollate.io/ai-2-0/how-to-guides/data-quality-observability/alerts-notifications/webhook-payloads-and-delivery.md).

## Endpoints

Base path: `/v1/events/subscriptions`

| Operation | Method and path |
| - | - |
| List alerts | `GET /v1/events/subscriptions` |
| Get by ID | `GET /v1/events/subscriptions/{id}` |
| Get by name | `GET /v1/events/subscriptions/name/{name}` |
| Create | `POST /v1/events/subscriptions` |
| Create or update by name | `PUT /v1/events/subscriptions` |
| Update with JSON Patch | `PATCH /v1/events/subscriptions/{id}` or `/name/{name}` |
| Delete | `DELETE /v1/events/subscriptions/{id}` or `/name/{name}` |
| Available sources, filters, and triggers | `POST /v1/events/subscriptions/capabilities` |
| Test a destination | `POST /v1/events/subscriptions/testDestination` |

## Permissions

Creating an alert requires **Create** permission on the `EventSubscription` entity. Deleting requires **Delete**, and reading delivery status requires view access to all alerts. See [Roles and Policies](https://docs.getcollate.io/ai-2-0/admin-guide/roles-policies.md).

## Alert Types

Set `alertType` to one of the following when you create an alert:

| Value | Use |
| - | - |
| `Observability` | Data health alerts: test results, pipeline status, schema and metric changes, data contract status. Uses triggers (`input.actions`) and filters (`input.filters`). |
| `Notification` | Metadata and collaboration events, including incidents through the `task` source. Uses filters only. |

The values `ActivityFeed`, `GovernanceWorkflowChangeEvent`, and `Custom` are used by system subscriptions. Don't create alerts with them.

## Request Schema

The request body for create and create-or-update is a `CreateEventSubscription` object.

**name** `string` *required*

Unique name of the alert.

**alertType** `string` *required*

`Observability` or `Notification`. See [Alert Types](#alert-types).

**displayName** `string`

Name shown in the UI.

**description** `string`

Description in Markdown format.

**owners** `array`

Owners of the alert, as entity references.

**enabled** `boolean` (default: true)

Whether the alert is active. A disabled alert doesn't read or deliver events.

**resources** `array` *required*

The alert **sources**, for example `["testCase"]` or `["pipeline", "ingestionPipeline"]`. Provide at least one value. Use lowercase `all` to match every source on a Notification alert. To check which sources you can combine and what they support, see [Available Sources, Filters, and Triggers](https://docs.getcollate.io/ai-2-0/developer-guide/api-reference/alerts/list.md#available-sources-filters-and-triggers).

**input** `object`

Filters and triggers.

**properties**

**filters** `array`

Conditions that narrow which events qualify. Each item is an [argument input](#argument-input).

**actions** `array`

Triggers, for Observability alerts only. Each item is an [argument input](#argument-input). Notification alerts ignore this list.

**destinations** `array`

Where to deliver the alert. See [Destination](#destination).

**pollInterval** `integer`

How often, in seconds, Collate checks for new events. The create request defaults to 10.

**batchSize** `integer`

Maximum number of events to process in each check. The create request defaults to 10.

**retries** `integer` (default: 3)

Stored with each failed event record. Collate doesn't use it to redeliver. See [Webhook Payloads and Delivery](https://docs.getcollate.io/ai-2-0/how-to-guides/data-quality-observability/alerts-notifications/webhook-payloads-and-delivery.md#retries).

**notificationTemplate** `object`

Entity reference to a user-created notification template. Applies to Slack, Teams, Google Chat, and Email destinations.

**domains** `array`

Fully qualified names of the domains the alert belongs to.

### Argument Input

Each filter and trigger is an object with these fields:

**name** `string` *required*

Name of the filter or trigger, for example `filterByFqn` or `GetTestCaseStatusUpdates`. Valid names depend on the sources. To look them up, see [Available Sources, Filters, and Triggers](https://docs.getcollate.io/ai-2-0/developer-guide/api-reference/alerts/list.md#available-sources-filters-and-triggers).

**effect** `string` (default: include)

`include` delivers the event when the condition matches. `exclude` silences it.

**prefixCondition** `string` (default: AND)

`AND` or `OR`. How this condition joins the previous one.

**arguments** `array`

Values for the filter or trigger. Each item is `{ "name": "<argument name>", "input": ["<value>", ...] }`. Every argument the filter or trigger defines must have at least one value.

With several sources, a filter must be supported by every source, because it applies to every event. A trigger must be supported by at least one source, and it applies only to the sources that support it.

Collate returns a `400` error when:

* You provide no source.
* You combine `all` with other sources.
* You combine sources of different kinds, such as `table` and `conversation`.
* A filter isn't supported by every source, or a trigger isn't supported by any source.
* A required argument is empty.

### Destination

Each item in `destinations` has these fields:

**category** `string` *required*

Who receives the alert: `External`, `Admins`, `Owners`, `Followers`, `Assignees`, `Mentions`, `Users`, or `Teams`.

**type** `string` *required*

Delivery channel: `Webhook`, `Slack`, `MsTeams`, `GChat`, `Email`, or `ActivityFeed`.

**enabled** `boolean` (default: true)

Whether this destination is active.

**timeout** `integer` (default: 10)

Connection timeout in seconds. Collate keeps it between 5 and 30.

**readTimeout** `integer` (default: 12)

Read timeout in seconds. Collate keeps it between 10 and 120.

**config** `object`

Channel settings. Required when `category` is `External`.

**Webhook, Slack, MsTeams, and GChat**

**endpoint** `string` *required*

Destination URL.

**httpMethod** `string` (default: POST)

`POST` or `PUT`. Alert deliveries are always sent as `POST`. This setting applies only when you test the destination.

**headers** `object`

Custom request headers, as key-value pairs.

**queryParams** `object`

Custom query parameters, as key-value pairs.

**authType** `object`

Authentication. One of:

* `{ "type": "bearer", "secretKey": "<secret>" }`: Collate signs each request body with the secret and sends the signature in the `X-OM-Signature` header.
* `{ "type": "oauth2", "tokenUrl": "...", "clientId": "...", "clientSecret": "...", "scope": "..." }`
* Omit `authType` for no authentication.

**Email**

**receivers** `array` *required*

Email addresses to send to.

> [!NOTE]
>
> Alerts that the API returns also include read-only fields such as `id`, `version`, `filteringRules` (the filters and triggers expanded into conditions), and `statusDetails` on each destination.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.