# Alerts

Get an alert when there is a new post that matches one or more search queries.

You may send alerts to email, Slack or a webhook.

## Alerts and Projects
Alerts live in Projects, so that you can organize them.

```
Project          one thing you monitor, usually one customer or competitor
  Alert          one notification, on or off
    Search       what it looks for. An alert can have up to 10 searches.
    Destination  where it delivers. Email, Slack, or a webhook
```

A post creates a hit when any one of the alert's searches matches it.

## Setting one up

### 1. Test the query first

Try some searches, and look at the results. An alert is only as good as its query.

```bash
curl -H "Authorization: Bearer $SPUTNIK_TOKEN" \
  -G --data-urlencode 'q="Acme Corp" OR "acme.com"' \
  --data-urlencode 'window=month' \
  "https://sputnikintelligence.com/api/v1/posts/search"
```

If you get too many results, tighten the phrase. If you get nothing, your brand name may be a common word. Pair it with something: `"Acme" AND (pricing OR funding)`. See [Search](/docs/search).

### 2. Create a project

Every alert belongs to a project. A project is one thing you monitor, usually one of your customers or one competitor. It keeps fifty alerts organised, and it lets you switch off a whole customer's monitoring in one move.

```bash
curl -X POST -H "Authorization: Bearer $SPUTNIK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp"}' \
  "https://sputnikintelligence.com/api/v1/projects"
```

### 3. Create the alert

You can give it its first search in the same call.

```bash
curl -X POST -H "Authorization: Bearer $SPUTNIK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Acme brand mentions",
        "project": "<project-slug>",
        "search": { "q": "\"Acme Corp\" OR \"acme.com\"", "name": "Brand" }
      }' \
  "https://sputnikintelligence.com/api/v1/alerts"
```

### 4. Give it somewhere to deliver

A new alert delivers nowhere. It will find hits and tell nobody until you add a destination. This is the most common reason someone thinks their alert is broken.

```bash
curl -X POST -H "Authorization: Bearer $SPUTNIK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}' \
  "https://sputnikintelligence.com/api/v1/alerts/<alert-slug>/destinations"
```

## Where alerts can deliver

**Email.** Any address, including addresses outside your team. Add several to one alert if several people need it. Each email carries the post, the snippet, and which search matched.

**Slack.** Create an incoming webhook in Slack for the channel you want. Register it in Sputnik with `channel: "slack"`, then point an alert at it. Hits arrive as a formatted message with the title, publication, date and snippet.

```bash
curl -X POST -H "Authorization: Bearer $SPUTNIK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "#coverage", "url": "https://hooks.slack.com/services/...", "channel": "slack"}' \
  "https://sputnikintelligence.com/api/v1/webhooks"
```

**Webhooks.** A signed HTTP POST per hit, for putting hits into your own system. See [Webhooks](/docs/webhooks).

One alert can deliver to all three at once.

## Reading hits over the API

Hits are readable whether or not you set up delivery. This suits an agent that checks on its own schedule.

```bash
curl -H "Authorization: Bearer $SPUTNIK_TOKEN" \
  "https://sputnikintelligence.com/api/v1/alert-hits?alert=<slug>"
```

The `next_cursor` on this endpoint is a resume token. Store it and pass it back to get only what has arrived since. It keeps coming back non-null even when there is nothing new, so poll it on a schedule.

Each hit carries the post, the snippet, and which of the alert's searches matched.

## Rules worth knowing

**An alert starts from now.** A new search finds hits from the next run onward, and the first run looks back one day. It does not sweep the archive. Use search for history.

**Editing a search applies forward.** Changing a query does not re-run it over the past.

**Deleting a search switches it off instead of removing it.** Past hits exist because that search found them. Set `is_active` back to true to restore it.

**Adding a destination does not replay history.** Hits already delivered stay delivered. Connecting a webhook in week three will not fire hundreds of old events.

**Archiving a project switches off every alert in it.** Un-archiving the project leaves those alerts off. You turn them back on yourself.

## If an alert goes quiet

- Check it has a destination.
- Check `is_delivering` on the destination. False means the webhook behind it switched itself off after repeated failures.
- Run the query as a search. If search finds nothing this week either, the alert is working.