Your first alert

An alert watches the corpus and tells you when something new matches. This is the thing most people come here for. Three steps.

1. Test the search first

Do this before creating anything. An alert is only as good as its query, and the cheapest place to find out that yours matches every article about a common word is a search:

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"

Look at what comes back. Too much? Tighten the phrase. Nothing? Your brand name may be a common word, in which case pair it with something — "Acme" AND (pricing OR funding). Search syntax has the details.

2. Create a project, then the alert

Every alert lives in a project. A project is one thing you monitor for — usually one of your own customers, or one competitor. It exists so that fifty alerts stay organised, and so you can archive a whole customer's monitoring in one move when they leave.

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

Then the alert, with its first search in the same call:

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"

3. Give it somewhere to deliver

A new alert delivers nowhere. It will find hits and tell nobody until you add a destination. That state is legal — the app flags it — and it is the single most common reason someone thinks their alert is broken.

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"

Slack and webhooks work the same way, through a registered endpoint — see Email and Slack.

What happens next

It starts from now. A search added today finds hits from the next run onwards, and the first run looks back one day. It does not sweep the archive: an alert reports new things, and the history of a query is what search is for. If you want the back catalogue, run the search.

Hits are also readable over the API, whether or not you set up delivery:

curl ... "https://sputnikintelligence.com/api/v1/alert-hits?alert=<slug>"

That endpoint is a resumable stream — store its next_cursor and pass it back to get only what is new. It is the right shape for an agent polling on a schedule.

If it goes quiet

• Check it has a destination. Still the most likely answer.
• Check is_delivering on the destination. False means the webhook behind it switched itself off after repeated failures.
• Check the query in search. If search finds nothing this week either, the alert is working and the world is quiet.