> 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

{% hint style="info" %}
`GET /v1/top-news`  ·  header `X-API-Key: sk_live_...`  ·  `category` is required  ·  items carry the [News Item Fields](/docs/api-reference/news-item-fields.md) 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 24 hours.

<figure><img src="/files/VVx8N0y7XCgVfa5TjM41" alt="A Top News ranking module rendered from this API"><figcaption><p>A Top News ranking module rendered from this API</p></figcaption></figure>

## 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` |

## How the ranking works

|            |                                                                                                                       |
| ---------- | --------------------------------------------------------------------------------------------------------------------- |
| Recomputed | Hourly, on the hour                                                                                                   |
| Window     | Everything published in the last 24 hours at impact 4 and 5                                                           |
| 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 |
| `rankedAt` | 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

**Request** (e.g. crypto top news in English)

```
GET https://api.flash.im/v1/top-news?category=crypto&lang=en
X-API-Key: sk_live_...
```

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](/docs/api-reference/news-feed-api.md)                           |

**No `limit`, no cursor.** 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",
  "rankedAt": "2026-08-11T09:00:00Z",
  "items": [
    {
      "rank": 1,
      "id": "n_4t8wq1",
      "headline": "SEC approves options trading on 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,
      "sentiment": "Mildly Bullish",
      "eventType": "regulation-action",
      "impactScore": 84,
      "entities": [
        { "name": "U.S. Securities and Exchange Commission", "aliases": ["SEC"], "ticker": null },
        { "name": "Bitcoin", "aliases": ["BTC"], "ticker": "BTC" }
      ],
      "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-bitcoin-split.jpg", "width": 1750, "height": 1000 } ],
      "sourceImageUrl": "https://assets.bwbx.io/images/....jpg",
      "categories": ["crypto"],
      "coins": [ { "cmcId": 1, "name": "Bitcoin", "symbol": "BTC" } ],
      "lang": "en"
    },
    {
      "rank": 2,
      "id": "n_9k2mf7",
      "headline": "US spot bitcoin ETFs snap ten-day slide",
      "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,
      "sentiment": "Mildly Bullish",
      "eventType": "market-move",
      "impactScore": 68,
      "entities": [ { "name": "Bitcoin", "aliases": ["BTC"], "ticker": "BTC" } ],
      "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"],
      "coins": [ { "cmcId": 1, "name": "Bitcoin", "symbol": "BTC" } ],
      "lang": "en"
    },
    { "...": "ranks 3 to 10, same schema" }
  ]
}
```

## Polling

{% hint style="warning" %}
The ranking regenerates on the hour, so **poll once an hour, at 10 minutes past the hour** (01:10, 02:10, ...). Polling more often returns the same set.
{% endhint %}

## Usage patterns

**1. Home screen "Top News" module** (the standard integration)

```
GET https://api.flash.im/v1/top-news?category=crypto
```

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 `rankedAt` 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. Every ranked item is impact 4 or 5, so `whyItMatters` is present on most of them: this makes a ready-made morning brief.

**3. Multilingual ranking** (one snapshot, every locale)

```
GET https://api.flash.im/v1/top-news?category=crypto&lang=ko
```

Same stories, same order, same `rankedAt` in every language; only the content is translated. Serve all your locales from the same hourly poll.