Skip to content
Statsy
Sign inStart free trial

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.

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

Alerts

Method and pathPurpose
GET /sites/:site/alertsLists alert rules.
POST /sites/:site/alertsCreates a rule. Returns 201.
GET /sites/:site/alerts/:idReads one rule.
PATCH /sites/:site/alerts/:idChanges config, channels or enabled.
DELETE /sites/:site/alerts/:idDeletes it.
POST /sites/:site/alerts/:id/testSends a test to every channel and returns what happened.
GET /sites/:site/alerts/:id/eventsThe 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 pathPurpose
GET /sites/:site/shareLists share links.
POST /sites/:site/shareCreates one. Returns 201 with the URL.
PATCH /sites/:site/share/:idChanges the password, name, visibility or expiry.
DELETE /sites/:site/share/:idRevokes 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.

Last updated · Markdown version