# Alerts and share links API

> Manage alert rules and their delivery channels, send a test, read the firing history, and create or revoke share links.

Section: CLI, MCP and API  
Canonical page: https://statsy.co/docs/developers/api-alerts-and-share  
Last updated: 2026-09-15

Two small resources that mostly exist so automation can set up a new site the same way every time.

## Alerts

| Method and path | Purpose |
| --- | --- |
| `GET /sites/:site/alerts` | Lists alert rules. |
| `POST /sites/:site/alerts` | Creates a rule. Returns 201. |
| `GET /sites/:site/alerts/:id` | Reads one rule. |
| `PATCH /sites/:site/alerts/:id` | Changes `config`, `channels` or `enabled`. |
| `DELETE /sites/:site/alerts/:id` | Deletes it. |
| `POST /sites/:site/alerts/:id/test` | Sends a test to every channel and returns what happened. |
| `GET /sites/:site/alerts/:id/events` | The last hundred times it fired, with the payload. |

`kind` is one of `goal`, `revenue`, `traffic_drop`, `traffic_spike`, `conversion_drop` and `tracking_lost`. Threshold kinds take a `config` of `{threshold_pct, window}`, where the window is `1h` or `24h`. A rule needs between one and ten channels.

```bash
curl -X POST -H "Authorization: Bearer sta_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "traffic_drop",
    "config": {"threshold_pct": 40, "window": "1h"},
    "channels": [{"kind": "email", "target": "team@example.com"}]
  }' \
  "https://statsy.co/api/v1/sites/ws_yoursitekey/alerts"
```

When a rule uses a webhook channel, the response includes a generated signing secret once, as `webhook_secrets`. Copy it then; it is not shown again. Slack, Discord and webhook URLs are checked before they are saved, and one that points somewhere unsafe is refused with `400 unsafe_url`.

## Share links

| Method and path | Purpose |
| --- | --- |
| `GET /sites/:site/share` | Lists share links. |
| `POST /sites/:site/share` | Creates one. Returns 201 with the URL. |
| `PATCH /sites/:site/share/:id` | Changes the password, name, visibility or expiry. |
| `DELETE /sites/:site/share/:id` | Revokes it immediately. |

```bash
curl -X POST -H "Authorization: Bearer sta_your_token" \
  -H "Content-Type: application/json" \
  -d '{"name":"Investor update","password":"a-long-passphrase","expiresAt":"2026-12-31T00:00:00Z"}' \
  "https://statsy.co/api/v1/sites/ws_yoursitekey/share"
```

`public` defaults to `true`. A `password` must be at least ten characters, and sending `null` in a `PATCH` removes it. `expiresAt` must be in the future, and `null` makes the link permanent.

Each link comes back with its `token`, the full `url`, whether it has a password, and the flags `expired`, `active` and `views`. Creating the first link on a site whose sharing is off turns sharing on.

> **Note.** Share links show aggregate metrics only. Visitor lists, journeys and replays are never included. If a link stops working, see [Share link problems](https://statsy.co/docs/troubleshooting/sharing).

Previous: [Payment API](https://statsy.co/docs/developers/api-payments)  
Next: [Sites and team API](https://statsy.co/docs/developers/api-sites-and-team)