> For the complete documentation index, see [llms.txt](https://docs.flash.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flash.im/docs/api-reference/top-news-api.md).
# Top News API
Ranked snapshot of what matters most, per category.
{% hint style="info" %}
`GET /v1/top-news` · header `Authorization: Bearer sk_live_...` · `category` is required · items carry the News Item Fields schema plus `rank`
{% endhint %}
## Purpose
The ranked snapshot: what matters most in a category right now. FLASH ranks the 10 most important stories from the last 48 hours.
A Top News ranking module rendered from this API
## Where to use it
| Your UX surface | How |
| ---------------------------------- | --------------------------------------------------------------- |
| Home screen "Top News" module | Render rank + headline, link out per item |
| Daily highlight widget / dashboard | Render ranks 1 to 5 with covers and `whyItMatters` when present |
## Usage patterns
One decision: the category. The ranking, the order, and the timing are the same for every caller.
One complete call to start from; swap in the category:
```bash
curl "https://api.flash.im/v1/top-news?category=crypto" \
-H "Authorization: Bearer sk_live_..."
```
Template:
```
GET /v1/top-news?category={category}&lang={language}&fields={fields}
```
**1. Home screen "Top News" module** (the standard integration)
The complete call above is this pattern. Render `rank` as the badge (#1 to #10) and `headline` as the row text; that two-column look is what users expect from a ranking. Link each row to `sourceUrl`, and show `generatedAt` as "Updated N minutes ago". Render however many items arrive; never pad to 10.
**2. Daily highlight / dashboard brief**
```
GET https://api.flash.im/v1/top-news?category=economy&fields=headline,impact,covers,whyItMatters,publishedAt
```
Render ranks 1 to 5 as cards: `covers[0]`, headline, impact dots, and `whyItMatters` as a one-line callout. Most ranked items are impact 4 or 5. On quiet days impact 3 items can fill the lower ranks, and `whyItMatters` may be null, so handle the empty case.
**3. Multilingual ranking** (one snapshot, every locale)
```
GET https://api.flash.im/v1/top-news?category=crypto&lang=ko
```
Same stories, same order, same `generatedAt` in every language; only the content is translated. Serve all your locales from the same hourly poll.
## How the ranking works
| | |
| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
| Recomputed | Hourly, on the hour |
| Window | Everything published in the last 48 hours, impact 4 and 5 first |
| Ordering | Higher impact first. Within the same impact, an event that several outlets have covered recently comes first |
| One event, one row | Reports of the same event are grouped, and one representative article is shown |
| Size | Up to 10 items, fewer on slow news days (weekends, holidays) |
| Languages | Language-invariant: `lang=ko` and `lang=ja` return the same stories in the same order. Only the content is translated |
| `generatedAt` | When the ranking was computed. Recommended display: "Updated N minutes ago" |
{% hint style="warning" %}
Render however many items arrive. **Never pad to 10.**
{% endhint %}
## Endpoint
The four rankings, one per category (`category` is required):
| Ranking | URL |
| ----------- | ------------------------------------------------------- |
| Crypto | `https://api.flash.im/v1/top-news?category=crypto` |
| Economy | `https://api.flash.im/v1/top-news?category=economy` |
| Politics | `https://api.flash.im/v1/top-news?category=politics` |
| Geopolitics | `https://api.flash.im/v1/top-news?category=geopolitics` |
Add `lang` for any of the 16 languages (default `en`).
| Parameter | Required | Description |
| ---------- | -------- | --------------------------------------------------------------------------------------- |
| `category` | **Yes** | One of `crypto`, `economy`, `politics`, `geopolitics`. Rankings exist per category only |
| `lang` | No | One of 16 languages (default `en`) |
| `fields` | No | Same as News Feed API |
**No `limit`, no paging.** The response is the top list itself.
**Response** (ranks 1 and 2 shown in full; items carry the complete News Item Fields schema plus `rank`)
```json
{
"category": "crypto",
"generatedAt": "2026-08-11T09:00:00Z",
"items": [
{
"rank": 1,
"id": "n_4t8wq1",
"headline": "SEC approves options trading on spot bitcoin ETFs",
"sourceHeadline": "SEC Signs Off on Options Trading for Spot Bitcoin ETFs",
"summary": "The US Securities and Exchange Commission approved options trading on spot bitcoin ETFs...",
"body": "The approval covers eleven listed funds...",
"whyItMatters": "Options unlock institutional hedging strategies that spot ETFs alone could not support.",
"impact": 5,
"eventType": "regulation-action",
"impactScore": 84,
"entities": [
{ "name": "U.S. Securities and Exchange Commission", "aliases": ["SEC"], "ticker": null, "entitySentiment": "Neutral" },
{ "name": "Bitcoin", "aliases": ["BTC"], "ticker": "BTC", "entitySentiment": "Positive" }
],
"source": { "name": "Bloomberg", "logoUrl": "https://.../sources/bloomberg.com.png" },
"sourceUrl": "https://www.bloomberg.com/news/articles/...",
"publishedAt": "2026-08-11T06:12:00Z",
"clusterId": "ev_11871203",
"relatedCount": 21,
"covers": [
{ "url": "https://.../covers/sec-1.jpg", "width": 1750, "height": 1000 },
{ "url": "https://.../covers/bitcoin-1.jpg", "width": 1750, "height": 1000 }
],
"sourceImageUrl": "https://assets.bwbx.io/images/....jpg",
"categories": ["crypto"],
"lang": "en"
},
{
"rank": 2,
"id": "n_9k2mf7",
"headline": "US spot bitcoin ETFs snap ten-day slide",
"sourceHeadline": "Bitcoin ETFs post $221 million inflow, ending 10-day outflow streak",
"summary": "US spot bitcoin ETFs recorded $221 million of net inflows...",
"body": "BlackRock's IBIT led the inflows...",
"whyItMatters": "A flow reversal at this scale often marks a shift in institutional positioning.",
"impact": 4,
"eventType": "market-move",
"impactScore": 68,
"entities": [ { "name": "Bitcoin", "aliases": ["BTC"], "ticker": "BTC", "entitySentiment": "Positive" } ],
"source": { "name": "Reuters", "logoUrl": "https://.../sources/reuters.com.png" },
"sourceUrl": "https://www.reuters.com/markets/...",
"publishedAt": "2026-08-11T09:41:00Z",
"clusterId": "ev_11820089",
"relatedCount": 13,
"covers": [ { "url": "https://.../covers/bitcoin-1.jpg", "width": 1750, "height": 1000 } ],
"sourceImageUrl": "https://www.reuters.com/resizer/v2/....jpg",
"categories": ["crypto", "economy"],
"lang": "en"
},
{ "...": "ranks 3 to 10, same schema" }
]
}
```
Rank 1 carries two covers (one per entity: SEC and Bitcoin): crop the two into a split cover, or use the first alone.
## Freshness
{% hint style="warning" %}
The ranking regenerates **on the hour**. Call it whenever the module renders; identical URLs are served from cache, and a new set appears each hour. A server-side pipeline that ingests the ranking needs only one fetch per hour.
{% endhint %}
## FAQ
Why did I get fewer than 10 items?
Slow news days (weekends, holidays) can rank fewer than 10. Render however many arrive; never pad the list.
Does the order change per language?
No. The ranking is language-invariant: same stories, same order, same `generatedAt` in all 16 languages. Only the content is translated.
When does the ranking update?
On the hour. Call it whenever your module renders; identical URLs are served from cache, and a new set appears each hour. A pipeline needs one fetch per hour.
Is there a ranking across all categories combined?
No. Rankings exist per category only, and `category` is required. Run two modules side by side if you need more than one.
