> 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/news-feed-api.md).

# News Feed API

{% hint style="info" %}
`GET /v1/news`  ·  header `X-API-Key: sk_live_...`  ·  every item carries the full [News Item Fields](/docs/api-reference/news-item-fields.md) schema
{% endhint %}

## Purpose

A real-time stream of every analyzed article. Each item arrives with the full analysis attached: impact, sentiment, event type, entities, cover, and 16-language renditions. This is the feed you build a news tab on.

<figure><img src="/files/9UrwnKnZoHNy9Hcbl7yL" alt="A news feed rendered from this API"><figcaption><p>A news feed rendered from this API</p></figcaption></figure>

## Where to use it

| Your UX surface                       | How                                          |
| ------------------------------------- | -------------------------------------------- |
| News tab / main news feed             | Full stream, filtered by `category`          |
| "Important only" stream               | `impact=4,5`                                 |
| Compact widget next to a price ticker | `fields` to trim the payload (example below) |

## Endpoint

```
GET /v1/news
```

The five base feeds, each returning the latest news:

| Feed           | URL                                                 |
| -------------- | --------------------------------------------------- |
| All categories | `https://api.flash.im/v1/news`                      |
| Crypto         | `https://api.flash.im/v1/news?category=crypto`      |
| Economy        | `https://api.flash.im/v1/news?category=economy`     |
| Politics       | `https://api.flash.im/v1/news?category=politics`    |
| Geopolitics    | `https://api.flash.im/v1/news?category=geopolitics` |

Add the parameters below to filter and shape the response:

| Parameter          | Description                                                                                                                                                                                                                                                                                                   |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `category`         | `crypto`, `economy`, `politics`, `geopolitics`. Omit = all                                                                                                                                                                                                                                                    |
| `impact`           | Tiers to include, comma-separated: `impact=4,5`. Omit = all (2 to 5)                                                                                                                                                                                                                                          |
| `lang`             | One of 16 languages (default `en`)                                                                                                                                                                                                                                                                            |
| `limit`            | How many items one call returns (up to 50). Match it to how many you display                                                                                                                                                                                                                                  |
| `since` / `cursor` | [Incremental fetching](/docs/api-reference/incremental-fetching-and-rate-limits.md)                                                                                                                                                                                                                           |
| `fields`           | Comma list of fields to return. Omit = all. Unknown field names return 400 with the allowed list. Example: a compact widget next to a ticker needs only `fields=headline,impact,covers,publishedAt`. `id` and the envelope fields (`hasMore`, `nextCursor`) are always included, so never list them in fields |

## Example

**Request** (e.g. the 20 latest impact 3, 4 and 5 crypto news in English)

```
GET https://api.flash.im/v1/news?category=crypto&impact=3,4,5&lang=en&limit=20
X-API-Key: sk_live_...
```

**Response** (one item shown in full; every item carries the complete News Item Fields schema)

```json
{
  "items": [
    {
      "id": "n_8f3k2p",
      "headline": "Spot bitcoin ETFs snap ten-day slide with $221M inflow",
      "summary": "US spot bitcoin ETFs recorded $221 million of net inflows on Tuesday, ending a ten-day outflow streak.",
      "body": "BlackRock's IBIT led the inflows with $130 million, followed by Fidelity's FBTC...",
      "whyItMatters": "A flow reversal at this scale often marks a shift in institutional positioning.",
      "impact": 4,
      "sentiment": "Mildly Bullish",
      "eventType": "market-move",
      "impactScore": 76,
      "entities": [
        { "name": "Bitcoin", "aliases": ["BTC"], "ticker": "BTC" },
        { "name": "BlackRock", "aliases": ["IBIT"], "ticker": "BLK" }
      ],
      "source": { "name": "Reuters", "logoUrl": "https://.../sources/reuters.com.png" },
      "sourceUrl": "https://www.reuters.com/markets/currencies/bitcoin-etfs-inflow",
      "publishedAt": "2026-08-11T09:14: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"
    },
    { "...": "next items, same schema" }
  ],
  "hasMore": true,
  "nextCursor": "c_9d2f1a"
}
```

## Usage patterns

**1. News tab** (the standard integration)

```
GET https://api.flash.im/v1/news?category=crypto&lang=en&limit=20
```

Render per item: `covers[0]` as the card image, `headline`, `summary`, impact dots from `impact`, `sentiment`, `source.name` with `source.logoUrl`, and relative time from `publishedAt`. Link the card to `sourceUrl`. Poll every 10 minutes with `cursor`; only new items arrive (see [Incremental Fetching](/docs/api-reference/incremental-fetching-and-rate-limits.md)).

**2. Important-only stream** (a "what matters" surface, push candidates)

```
GET https://api.flash.im/v1/news?category=crypto&impact=4,5&limit=10
```

Only impact 4 and 5 arrive, and these are the items that carry `whyItMatters`: render it as a one-line callout under the summary. Volume is a handful of items per day, which fits digest screens and push notification queues.

**3. Compact widget next to a ticker** (minimum payload)

```
GET https://api.flash.im/v1/news?category=crypto&fields=headline,impact,covers,publishedAt&limit=5
```

Four fields render a small card list: thumbnail, headline, dots, time. `id` is always included, so deduplication still works.

**4. Multilingual feeds** (one integration, every locale)

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

Pass your user's language in `lang` and render the same layout. Nothing else in your integration changes per language.