Projects and alerts

Four things, nested:

Project          one thing you monitor for — usually one customer
  └─ Alert       one notification, on or off
       ├─ Search what it looks for (up to 10)
       └─ Destination  where it delivers (email, Slack, webhook)

If you just want one working, Your first alert walks it end to end. This page is why it is shaped this way.

Projects

A project groups alerts by what they are for. An agency running fifty clients wants fifty projects, not fifty loose alerts — and when a client leaves, archiving the project switches off everything in it in one move.

Archiving is is_active: false. It switches off every alert inside. Un-archiving restores the project but leaves those alerts off: turning monitoring back on should be a decision you make, not a side effect of restoring a folder.

Deleting a project takes its alerts and their hits with it. Archive if you want the history.

Alerts

An alert is the notification. Its name is what you see when it fires, so name it for what it tells you — "Acme brand mentions", not "alert 3".

Editing an alert changes only what is true of the notification: its name, its project, whether it is on. What it looks for lives on its searches; where it goes lives on its destinations.

Searches

An alert holds up to ten saved searches, and a post hits the alert if any of them matches. That is the structure to use for "the several ways people write our name": one alert, several searches, one notification.

A search takes q plus the same filter names GET /posts/search takes, so a search you tested lifts straight in without renaming anything. Each one can carry a label, which comes back on the hit — so an alert with several searches tells you which one fired.

Edits apply forward only. Changing a search does not re-run it over the past; that would report old posts as news.

Deleting a search deactivates it rather than removing it. Hits exist because a search found them, and deleting it outright would orphan that explanation. Set is_active back to true to restore it.

Destinations

An email address, or one of your team's registered webhooks. An alert with no destinations still finds hits and tells nobody.

Adding a destination does not replay history. Hits already delivered stay delivered, so connecting a webhook in week three does not fire hundreds of events about things you have already seen.

Watch is_delivering. It is false when the destination is on but the webhook behind it has deactivated itself after repeated failures — the field that tells you an alert has gone quiet for a reason you can fix.

Reading hits

GET /alert-hits returns hits across all your alerts, or one of them. Each carries the post, which searches matched, and the snippet — the evidence, so a hit is forwardable to a sceptical client as it stands.