Breaking news API: how to get high-urgency alerts in real time
Polling a headline endpoint every minute and eyeballing the results doesn't scale. A breaking-news API should tell you what's actually urgent — scored, filtered to your beat, and delivered the moment it lands. Here's how to set that up in a handful of calls.
What makes a story "breaking"?
The hard part isn't fetching headlines — it's deciding which ones matter. NewsAgent Data scores every article for urgency on a 0–10 scale as it's ingested, using a deterministic pattern engine (300+ signals: mass-casualty language, sanctions, central-bank moves, military escalation, disasters and more) rather than a black-box model. A 9 is a confirmed strike or a rate decision; a 2 is routine commentary. Because it's deterministic, the same input always gets the same score — so a threshold you set today still means the same thing next month.
1. Pull what's breaking right now
The /v1/breaking endpoint returns recent high-urgency items (score ≥ 7 by default). One call, already ranked:
curl -H "X-API-Key: YOUR_KEY" \ "https://api.newsagentdata.com/v1/breaking?min_score=8&days=1"
Every record comes back with urgency, political_lean, country_tags, topic_tags and a cluster_id — no enrichment to bolt on yourself.
2. Filter to your beat
Breaking is only useful if it's your breaking. Narrow by country, topic or audience so you're not drowning in noise:
curl -H "X-API-Key: YOUR_KEY" \ "https://api.newsagentdata.com/v1/feed?min_score=7&country=ua&topic=defense&days=1"
Country and language are separate axes, and topics, audiences and event types are pre-tagged — so "high-urgency defense news from Ukraine" is a filter, not a keyword list you have to maintain. See the coverage map and topics for what's available.
3. Push, don't poll
Polling burns quota and adds latency. Register a webhook and high-urgency items arrive at your endpoint within roughly 60 seconds of ingestion, HMAC-signed, with urgency and lean already attached:
POST /v1/webhook?url=https://your.app/hook&min_score=7
Prefer a long-lived connection? An SSE stream pushes the same events to a dashboard or alerting service without a reconnect loop. Either way you react to news instead of asking for it.
4. De-duplicate the same event
One missile strike becomes forty headlines. Items covering the same event share a cluster_id, and cluster_size tells you how widely a story has spread — a useful breaking signal in itself. Group by cluster and you alert once per event, not once per outlet.
Putting it together
A minimal breaking-news pipeline: register a webhook with min_score=7 filtered to your countries and topics, de-duplicate incoming items by cluster_id, and route anything scoring 9–10 to a faster channel. No NLP pipeline, no scraping, no scoring model to train — the data arrives ranked and labelled.
For the full parameter list see the API docs, and for a worked monitoring example read tracking sanctions news in real time.