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

# Alert Connectors API

> Manage inbound alert sources that open, update, and resolve Squasher incidents.

Alert connectors let external monitoring systems raise incidents inside
Squasher. Connector-created incidents have the `integration` source type and
flow through the project's existing notification routes.

Sources and destinations are separate. A source receives an alert from CloudWatch,
Alertmanager, Grafana, Datadog, PagerDuty-compatible producers, or a generic sender.
A [notification destination](/features/alerts) sends the resulting Squasher incident
to responders.

## Operations

| Operation                        | Method and path                                                                |
| -------------------------------- | ------------------------------------------------------------------------------ |
| `alertConnectors.catalog`        | `GET /v1/alert-connectors/catalog`                                             |
| `alertConnectors.list`           | `GET /v1/projects/{project_id}/alert-connectors`                               |
| `alertConnectors.create`         | `POST /v1/projects/{project_id}/alert-connectors`                              |
| `alertConnectors.get`            | `GET /v1/projects/{project_id}/alert-connectors/{connector_id}`                |
| `alertConnectors.listDeliveries` | `GET /v1/projects/{project_id}/alert-connectors/{connector_id}/deliveries`     |
| `alertConnectors.update`         | `PUT /v1/projects/{project_id}/alert-connectors/{connector_id}`                |
| `alertConnectors.delete`         | `DELETE /v1/projects/{project_id}/alert-connectors/{connector_id}`             |
| `alertConnectors.rotateSecret`   | `POST /v1/projects/{project_id}/alert-connectors/{connector_id}/rotate-secret` |
| `alertConnectors.test`           | `POST /v1/projects/{project_id}/alert-connectors/{connector_id}/test`          |

Management operations require project read or write permission. The inbound
endpoint authenticates AWS connectors with the SNS signature and exact topic
ARN. Webhook connectors use the write-only secret returned at creation or rotation;
the provider setup page specifies whether it belongs in a bearer header or payload.
Inbound endpoints are rate-limited at the edge before application processing. A
`429` response is retryable; preserve the original event identity and use
exponential backoff with jitter.

## Providers

| Provider                | `provider` value          | Authentication                    | Setup                                           |
| ----------------------- | ------------------------- | --------------------------------- | ----------------------------------------------- |
| AWS CloudWatch          | `aws_cloudwatch`          | SNS signature and exact topic ARN | [Guide](/integrations/aws-cloudwatch-alerts)    |
| Generic webhook         | `generic_webhook`         | Bearer secret                     | [Guide](/integrations/generic-alert-webhook)    |
| Prometheus Alertmanager | `prometheus_alertmanager` | Bearer secret                     | [Guide](/integrations/prometheus-alertmanager)  |
| Grafana Alerting        | `grafana`                 | Bearer secret                     | [Guide](/integrations/grafana-alerts)           |
| Datadog monitors        | `datadog`                 | Bearer secret                     | [Guide](/integrations/datadog-alerts)           |
| PagerDuty Events API v2 | `pagerduty_events_v2`     | `routing_key` secret              | [Guide](/integrations/pagerduty-events-inbound) |

## Create AWS CloudWatch

```json theme={null}
{
  "provider": "aws_cloudwatch",
  "display_name": "Production CloudWatch",
  "config": {
    "topic_arn": "arn:aws:sns:us-east-1:123456789012:production-alarms",
    "default_severity": "sev-1",
    "resolve_on_ok": true
  }
}
```

## Create a generic webhook

```json theme={null}
{
  "provider": "generic_webhook",
  "display_name": "Infrastructure alerts",
  "config": { "default_severity": "sev-2" }
}
```

Create and rotate responses include a `setup` object. Store its secret in a
secret manager; subsequent reads return only `secret_prefix`.

Because that secret is returned only once, create and rotate requests do not accept
`Idempotency-Key` and official clients do not retry them automatically. If the
response is interrupted, list the project's connectors before creating another one,
then rotate the existing connector if you need a new credential.

Rotation starts a 24-hour overlap window for the previous secret. Update the source
during that window, verify a provider-specific firing and recovery test, then let the
old credential expire. AWS connectors do
not expose this operation because SNS signatures authenticate their requests.

The `test` operation checks that the connector is enabled and reports whether Squasher
has received a provider delivery. It does not manufacture an incident or pretend to
test the upstream vendor. Use `listDeliveries` to inspect recent `opened`, `updated`,
`resolved`, `ignored`, and `failed` outcomes without exposing raw payloads or credentials.

## Paginate delivery history

Request a page size from 1 to 100 to receive a cursor page. Omit `cursor` on the
first request, then pass the returned `next_cursor` unchanged until it is `null`.
The cursor is opaque; do not parse or construct it.

```bash theme={null}
curl --get \
  --url "https://api.squasher.ai/v1/projects/$SQUASHER_PROJECT_ID/alert-connectors/$CONNECTOR_ID/deliveries" \
  --header "x-squasher-key: $SQUASHER_API_KEY" \
  --data-urlencode "limit=50"
```

```json theme={null}
{
  "data": [
    {
      "id": "2ebc8a7e-4a4f-4b8c-b389-c6f10f42fb3e",
      "connector_id": "f5bcd42f-e185-4cf3-bf80-0d32dbe90ef8",
      "provider_event_id": "monitor-123-1712345678",
      "external_alert_id": "monitor-123",
      "outcome": "opened",
      "incident_id": "inc_42",
      "error_code": null,
      "error_message": null,
      "received_at": "2026-08-05T12:00:00.000Z",
      "processed_at": "2026-08-05T12:00:00.120Z"
    }
  ],
  "next_cursor": "eyJpZCI6Ii4uLiJ9"
}
```

The TypeScript client can walk every page without manually handling cursors:

```ts theme={null}
for await (const delivery of client.alertConnectors.listDeliveries(CONNECTOR_ID, {
  limit: 50,
})) {
  console.log(delivery.outcome, delivery.external_alert_id);
}
```

The CLI exposes the same contract with `--limit` and `--cursor`. MCP agents can
discover it with `search("alertConnectors.listDeliveries")`; omit `cursor` on the
first `execute` call and reuse the response's `next_cursor` on the next call.

Calling the endpoint without `limit` or `cursor` still returns the legacy first-page
array for compatibility. New integrations should always request `limit` so they can
continue beyond the first 50 records.

`default_severity` is a project-configured incident-severity key, not a closed
enum. Existing legacy keys and additional ranks such as `sev-8` remain valid;
the value is bounded to 64 characters.

Deleting a connector immediately revokes its credentials and resolves any active
incidents owned by that connector. The connector disappears from management APIs,
while `listDeliveries` remains available for that connector ID and project during the
90-day delivery-audit retention window. Save the connector ID before deletion. The
response contains only sanitized delivery metadata; another project cannot read it.
The 90-day ledger bound applies to every outcome. Project deletion removes the
history immediately. Delivery rows expire even when the linked incident is still open;
the incident and its timeline remain available. Once a delivery identity has aged out,
reusing that identity can process a new request, subject to the normal lifecycle-ordering
checks.

Use `client.alertConnectors.*` in `@squasher-ai/api-client`,
`squasher alert-connectors`, or MCP `search("alertConnectors")`.

See [Inbound alert connectors](/integrations/alert-connectors) for lifecycle,
deduplication, security, and troubleshooting guidance.