> 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
Real-time stream of every analyzed article.
{% hint style="info" %}
`GET /v1/news` · header `Authorization: Bearer sk_live_...` · every item carries the full News Item Fields schema
{% endhint %}
## Purpose
A real-time stream of every analyzed article. Each item arrives with the full analysis attached: impact, event type, entities with their sentiment, cover, and 16-language renditions. This is the feed you build a news tab on.
A news feed rendered from this API (english)
A news feed rendered from this API (chinese)
## 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) |
| Section tab (ETFs, earnings, Middle East) | `subCategory` to narrow a category to one section |
| Feed without outlets you already carry | `excludeSources` to leave those outlets out |
## Usage patterns
The only decisions are the filters: pick a category, an impact floor, a language, and a size. Everything else arrives done.
One complete call to start from; swap in your own filters:
```bash
curl "https://api.flash.im/v1/news?category=crypto&lang=en&limit=20" \
-H "Authorization: Bearer sk_live_..."
```
Template:
```
GET /v1/news?category={category}&impact={tiers}&lang={language}&fields={fields}&limit={count}
```
**1. News tab** (the standard integration)
The complete call above is this pattern. Render per item: `covers[0]` as the card image, `headline`, `summary`, impact dots from `impact`, `source.name` with `source.logoUrl`, and relative time from `publishedAt`. Link the card to `sourceUrl`. Call it whenever the tab renders; identical URLs are served from cache. A server-side pipeline can poll with `after` to receive only what is new (see Integration Patterns).
**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 short 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.
**5. Section feed** (a tab narrower than a category)
```
GET https://api.flash.im/v1/news?subCategory=crypto-etf&limit=20
```
Every story carries up to two section slugs in `subCategories`, and `subCategory=` filters on them: an ETF tab, an earnings tab, a Middle East tab. Send several slugs for one tab (`subCategory=crypto-etf,etf-funds`) and combine them with any other filter (`category=crypto&subCategory=crypto-etf&impact=3,4,5`). The slugs are listed on the [Categories](/docs/api-reference/categories.md) page.
**6. Leaving out sources** (outlets you already carry, or do not want on your surface)
```
GET https://api.flash.im/v1/news?category=economy&excludeSources=17,18&limit=20
```
Reuters (17) and Bloomberg (18) are left out, and the other outlets still fill all 20 items: the exclusion is applied before `limit`, so leaving outlets out does not shorten your page. Every outlet's number is in the [Source numbers](/docs/api-reference/news-item-fields.md#source-numbers) table.
## 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` |
Combine categories with commas: `https://api.flash.im/v1/news?category=crypto,economy` returns the latest news from both.
Add the parameters below to filter and shape the response:
| Parameter | Description |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `category` | `crypto`, `economy`, `politics`, `geopolitics`. One or several, comma-separated: `category=crypto,economy` returns items in either, each once. Omit = all. Lower case only. A repeated `category=` parameter keeps only the first value |
| `impact` | Tiers to include, comma-separated: `impact=4,5`. Omit = all (2 to 5) |
| `subCategory` | Section slugs, comma-separated, 1 to 10: `subCategory=crypto-etf`. An item is included when it carries any one of them, together with your other filters. A slug that is not on the list returns an empty list rather than an error; 11 or more return 400 |
| `excludeSources` | Source numbers to leave out, comma-separated: `excludeSources=17,18`. Every outlet's number is in [Source numbers](/docs/api-reference/news-item-fields.md#source-numbers). Outlets are removed before `limit` applies, so the page still comes back full. A number not in the table, or a value that is not a number, is ignored with no error. A repeated `excludeSources=` parameter keeps only the first value. Top News and RSS do not take it |
| `lang` | One of 16 languages (default `en`). Any code the API does not recognise falls back to English with no error, so send an exact code such as `zh-CN` |
| `limit` | How many items one call returns (up to 100). Match it to how many you display. Fewer items than your `limit` means you reached the end |
| `before` / `after` | Time anchors for paging backward and forward. See Integration Patterns |
| `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` is always included, so never list it 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
Authorization: Bearer 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",
"sourceHeadline": "Bitcoin ETFs post $221 million inflow, ending 10-day outflow streak",
"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. Watch whether inflows hold through the rest of the week before reading it as a trend.",
"impact": 4,
"eventType": "market-move",
"impactScore": 76,
"entities": [
{ "name": "Bitcoin", "aliases": ["BTC"], "ticker": "BTC", "entitySentiment": "Positive" },
{ "name": "BlackRock", "aliases": ["IBIT"], "ticker": "BLK", "entitySentiment": "Positive" }
],
"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"],
"subCategories": ["crypto-etf", "crypto-markets"],
"lang": "en"
},
{ "...": "next items, same schema" }
]
}
```
## FAQ
How often should I call it?
For user-facing surfaces, call whenever the surface renders: identical URLs are served from cache, so per-render calls stay cheap. Server-side pipelines poll on a schedule with `after`. See Integration Patterns.
Do you offer WebSocket or push?
The API is HTTP GET by design. User-facing surfaces call on render and hit the cache; pipelines poll with `after` and de-duplicate by `id`. Neither needs a socket.
How do I receive every item without missing any?
Use `after`. Pass the `publishedAt` of the newest item you stored; each poll returns only what has arrived since, and after downtime you resume from that same value with nothing missed. The boundary is inclusive, so de-duplicate by `id`. The pattern is written out in Integration Patterns.
Can I get news for one specific asset or contract only?
That is the matching mode of this same endpoint: add `keyword` (assets) or `sentence` (contract questions). See the Match API.
Do all stories have images?
No. `covers[]` can be empty. Fall back in this order: your own default image, or text-only. `sourceImageUrl` (the outlet's own image) can also be hotlinked; rights remain with the outlet.
Can I read stories older than the latest 100?
The API serves the newest 100 per query. Deeper history is the store-and-serve pattern: poll with `after` and accumulate every item in your own database. See Integration Patterns.
