> 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-item-fields.md).

# News Item Fields

Every field a news item carries, and the 18 event types.

Every news-serving endpoint (`/v1/news`, including its matching mode, and `/v1/top-news`) returns items with this schema. Every item carries `id`, `publishedAt`, and `lang`; the rest fall into three groups.

<table data-view="cards"><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td><h4><i class="fa-newspaper" style="color:$primary;">:newspaper:</i></h4></td><td><strong>Content</strong><br>What happened</td><td><code>headline</code> <code>summary</code> <code>body</code></td></tr><tr><td><h4><i class="fa-brain" style="color:$primary;">:brain:</i></h4></td><td><strong>Intelligence</strong><br>What the event is and how much it matters</td><td><code>impact</code> <code>impactScore</code> <code>eventType</code> <code>whyItMatters</code> <code>entitySentiment</code></td></tr><tr><td><h4><i class="fa-link" style="color:$primary;">:link:</i></h4></td><td><strong>Source and joins</strong><br>Where it came from and what it connects to</td><td><code>source</code> <code>sourceUrl</code> <code>sourceHeadline</code> <code>sourceImageUrl</code> <code>entities</code> <code>categories</code> <code>subCategories</code> <code>clusterId</code> <code>relatedCount</code> <code>covers</code></td></tr></tbody></table>

<figure><img src="https://2934076593-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7M9iZ2Kg8fDpH37gsTL3%2Fuploads%2Faj2xLWnIHUTdZ6zYci0M%2Fmeta.png?alt=media&#x26;token=ac11aced-b379-4d03-9a37-56ab1e75b9b5" alt="How the fields render in a real feed"><figcaption><p>How the fields render: headline, impact dots, entity sentiment, source, cover</p></figcaption></figure>

## Schema

<table data-search="true"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>string</td><td>Unique news ID. Stable and permanent: an item's id never changes</td></tr><tr><td><code>headline</code></td><td>string</td><td>Rewritten headline</td></tr><tr><td><code>sourceHeadline</code></td><td>string</td><td>The original outlet's headline, as published. Use it when you want to show what the source itself said</td></tr><tr><td><code>summary</code></td><td>string</td><td>Short summary</td></tr><tr><td><code>body</code></td><td>string</td><td>Key-point body (fact based)</td></tr><tr><td><code>whyItMatters</code></td><td>string | null</td><td>Why this matters. AI-inferred. Two or three sentences: what the event changes, through what mechanism, and the next checkpoint that will show whether the effect holds. Present on impact 4 and 5, null below that, so always handle null</td></tr><tr><td><code>impact</code></td><td>number</td><td>2 to 5, higher = more important. Equals the dots on FLASH surfaces (●●●●○ = 4)</td></tr><tr><td><code>eventType</code></td><td>string</td><td>One of 18 types. Full table below</td></tr><tr><td><code>impactScore</code></td><td>number</td><td>0 to 100. Fine-grained importance under <code>impact</code>: use it to sort within a tier</td></tr><tr><td><code>entities[]</code></td><td>array</td><td><code>{ name, aliases[], ticker, entitySentiment }</code>. <code>name</code> = the entity's full name ("Federal Reserve"), <code>aliases</code> = other spellings it goes by ("Fed"), <code>ticker</code> = ticker symbol ("BTC"; null for non-assets). <code>entitySentiment</code> describes how this event bears on that entity (see below). Names, aliases and tickers are always English</td></tr><tr><td><code>source</code></td><td>object</td><td>Original outlet: <code>{ name, logoUrl }</code>. <code>logoUrl</code> is the outlet's logo. Every outlet also has a number, which <code>excludeSources</code> takes to leave that outlet out: see <a href="/docs/api-reference/news-item-fields.md#source-numbers">Source numbers</a></td></tr><tr><td><code>sourceUrl</code></td><td>string</td><td>Link to the original article</td></tr><tr><td><code>publishedAt</code></td><td>string</td><td>ISO 8601 UTC</td></tr><tr><td><code>clusterId</code></td><td>string | null</td><td>Same event = same cluster. null when the article is not clustered</td></tr><tr><td><code>relatedCount</code></td><td>number</td><td>How many reports FLASH has published on this event so far, this item included: how much the event has been reported. Render the other reports as "+N more" (N = <code>relatedCount - 1</code>); hide it when <code>relatedCount</code> is 1. <strong>Omitted when <code>clusterId</code> is null</strong></td></tr><tr><td><code>covers[]</code></td><td>array</td><td>Cover images <code>{ url, width, height }</code>, one per matched entity: a story carries zero, one, or more. Each is 1750x1000, produced and licensed by FLASH. Empty = use your own fallback or render text-only; two covers can be cropped into a split cover</td></tr><tr><td><code>sourceImageUrl</code></td><td>string | null</td><td>The original article's OG image, hotlinked. Rights remain with the outlet</td></tr><tr><td><code>categories[]</code></td><td>array</td><td>The categories this article belongs to. An article can belong to more than one; crypto-native coverage stays in <code>crypto</code></td></tr><tr><td><code>subCategories[]</code></td><td>array</td><td>The sections this story belongs to, most central first: 0 to 2 slugs. Empty when no section fits and on stories analysed before sections launched. The full list is on the Categories page</td></tr><tr><td><code>lang</code></td><td>string</td><td>Language of this rendition</td></tr></tbody></table>

{% hint style="warning" %}
**Nulls to handle.** `whyItMatters` is null on impact 2 and 3. `entitySentiment` is null below impact 3, and on entities that have nothing to gain or lose (places, policy instruments, indicators). `relatedCount` is omitted entirely when `clusterId` is null. `subCategories` can be an empty array.
{% endhint %}

## impact

`impact` answers how much this event matters. On screen it renders as dots, and the number of dots is the value. Within one tier, `impactScore` (0 to 100) sets the order.

<figure><img src="https://2934076593-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7M9iZ2Kg8fDpH37gsTL3%2Fuploads%2FULGz6L86dGM5Cp6pRKee%2Fimpact-scale.png?alt=media" alt="The impact scale"><figcaption></figcaption></figure>

## entitySentiment

Sentiment is attached to each entity, not to the article. One event can help one party and hurt another, and a single article-level label cannot carry that. Every item in `entities[]` therefore carries its own sentiment.

<table data-search="false"><thead><tr><th>Field</th><th>Values</th><th>Meaning</th></tr></thead><tbody><tr><td><code>entitySentiment</code></td><td><code>Positive</code> · <code>Neutral</code> · <code>Negative</code> · <code>null</code></td><td>How the reported event bears on that entity</td></tr></tbody></table>

**`Neutral` and `null` are not the same thing, and they are not interchangeable.**

* `Neutral` is a judgment: the event was weighed against this entity and found not to move it. Offsetting effects, a procedural step with no outcome, a passing mention.
* `null` means there is nothing to weigh. The entity has nothing to gain or lose from events at all: a place, a policy instrument, an indicator.

**Where values appear.** Entity sentiment is produced for items at `impact` 3 and above. Below that every entity carries `null`.

**Politics and geopolitics carry values too.** Sentiment here describes standing, not merit: whether a named party gained or lost ground in the event as reported. It is not a verdict on who is right.

{% hint style="info" %}
This describes how the reported event bears on that entity. It is not a price prediction and not investment advice.
{% endhint %}

## clusterId and relatedCount

The same event is reported many times by many outlets. FLASH converges them into one event and returns one representative item with a related-coverage count.

<figure><img src="https://2934076593-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7M9iZ2Kg8fDpH37gsTL3%2Fuploads%2FshlKbC3p6x3Ba8gZO804%2Fcluster-merge.png?alt=media" alt="Many reports converge into one item"><figcaption></figcaption></figure>

`relatedCount` tells you how much the event has been reported so far: the number of reports FLASH has published on it, this item included. Every one of them shares the same `clusterId`.

* **It counts reports, not outlets.** An outlet's follow-ups on the same event each count.
* **It is cumulative.** The count rises while outlets keep reporting the event and does not fall when they stop.
* **It fills in over time.** A story that has just broken usually has no `relatedCount` yet, or a small one, because it has not been grouped with other reports. Many stories never get one.

Render the other reports as "+N more" next to the outlet name, where N = `relatedCount - 1`. Hide it when `relatedCount` is 1 (FLASH has published no other report on the event) or missing.

## subCategories

A sub-category is the section of a news site where the story would run: what the story is about. `categories` says which of the four feeds carry it, and `subCategories` says which section inside them it belongs to.

Every item carries the field: zero, one, or two slugs, the most central one first.

* **An empty list is a normal answer.** Sport, entertainment, lifestyle and local crime have no section here, and neither do stories that fit none of them cleanly.
* **Sections are independent of `categories`.** A story filed under `economy` can carry `energy` and `climate-disasters`, so read the two fields separately rather than deriving one from the other.
* **Stories analysed before sections launched carry an empty list.** Older items are not filled in, so a section feed accumulates from the day it starts.
* **Slugs are permanent.** New ones can be added at any time, so ignore a value you do not recognise instead of failing on it.

**Filtering.** Add `subCategory=` to `GET /v1/news`, in either mode:

```
GET /v1/news?subCategory=crypto-etf&limit=20
GET /v1/news?category=crypto&subCategory=crypto-etf,etf-funds&impact=3,4,5
GET /v1/news?keyword=Solana,SOL&category=crypto&subCategory=crypto-etf
```

One to ten slugs, comma-separated. An item is included when it carries any one of them, and the filter narrows whatever your other parameters already selected. A slug that is not on the list returns an empty list rather than an error, and 11 or more values return 400. Top News, RSS and NewsCover do not take this parameter.

The 59 slugs, grouped by category and with a call for each one, are on the [Categories](/docs/api-reference/categories.md) page.

## Source numbers

Every item names its outlet in `source.name`. Each outlet also has a number, and the number is what the `excludeSources` parameter takes when you want outlets left out of a feed: `excludeSources=17,18` leaves out Reuters and Bloomberg. Responses do not carry the number, so look it up here.

| No. | `source.name`               |
| --- | --------------------------- |
| 1   | Cointelegraph               |
| 2   | CoinDesk                    |
| 3   | The Daily Hodl              |
| 4   | Beincrypto                  |
| 5   | Decrypt                     |
| 6   | The Block                   |
| 7   | CryptoSlate                 |
| 8   | Bitcoin Magazine            |
| 9   | Protos                      |
| 10  | Politico                    |
| 11  | The Hill                    |
| 12  | Axios                       |
| 13  | Semafor                     |
| 14  | CNBC                        |
| 15  | Financial Times             |
| 16  | Al Jazeera                  |
| 17  | Reuters                     |
| 18  | Bloomberg                   |
| 19  | The Wall Street Journal     |
| 20  | The New York Times          |
| 21  | AP News                     |
| 22  | Fox News                    |
| 23  | CBS News                    |
| 24  | NBC News                    |
| 25  | The Washington Post         |
| 26  | CNN                         |
| 27  | The Guardian                |
| 28  | Forbes                      |
| 29  | Fortune                     |
| 30  | Benzinga                    |
| 31  | MS NOW                      |
| 32  | BBC                         |
| 33  | Foreign Policy              |
| 34  | SEC                         |
| 35  | CFTC                        |
| 36  | OFAC                        |
| 37  | International Monetary Fund |
| 38  | Federal Reserve             |
| 39  | FDIC                        |
| 40  | The White House             |
| 41  | ABC News                    |
| 42  | The Economist               |
| 43  | NPR                         |
| 44  | TechCrunch                  |
| 45  | DW                          |
| 46  | France 24                   |

`excludeSources` works on `GET /v1/news` in both modes, and the same exclusion applies to `fallback.items`. Top News and RSS do not take it. How it behaves is on the [News Feed API](/docs/api-reference/news-feed-api.md) page.

## eventType values (18)

<table data-search="false"><thead><tr><th>Family</th><th>eventType</th></tr></thead><tbody><tr><td>Policy, regulation, law</td><td><code>policy-decision</code>, <code>regulation-action</code>, <code>legal-action</code></td></tr><tr><td>Elections, appointments</td><td><code>election</code>, <code>appointment</code></td></tr><tr><td>Data</td><td><code>data-release</code>, <code>data-point</code></td></tr><tr><td>Corporate, funding</td><td><code>corporate-action</code>, <code>funding-deal</code></td></tr><tr><td>Security</td><td><code>security-incident</code></td></tr><tr><td>Disaster</td><td><code>disaster</code></td></tr><tr><td>Geopolitics, diplomacy</td><td><code>geopolitical-event</code>, <code>diplomatic-event</code></td></tr><tr><td>Statements, commentary</td><td><code>official-statement</code>, <code>analysis-commentary</code></td></tr><tr><td>Market, operations</td><td><code>market-move</code>, <code>ops-notice</code>, <code>digest</code></td></tr></tbody></table>

<table data-search="false"><thead><tr><th>eventType</th><th>Meaning</th></tr></thead><tbody><tr><td><code>policy-decision</code></td><td>Policy decisions by central banks or governments (rate decisions, executive orders)</td></tr><tr><td><code>data-release</code></td><td>Scheduled official data releases (inflation, jobs, GDP)</td></tr><tr><td><code>regulation-action</code></td><td>Regulators acting: approvals, sanctions, rulemaking</td></tr><tr><td><code>legal-action</code></td><td>Lawsuits, indictments, court rulings</td></tr><tr><td><code>security-incident</code></td><td>Hacks, exploits, breaches</td></tr><tr><td><code>corporate-action</code></td><td>Corporate actions executed: M&#x26;A, listings, launches, restructuring</td></tr><tr><td><code>funding-deal</code></td><td>Fundraises and fund formations</td></tr><tr><td><code>geopolitical-event</code></td><td>Conflicts, sanctions, and security events between states</td></tr><tr><td><code>official-statement</code></td><td>Officials or institutions speaking (a statement, not an action)</td></tr><tr><td><code>market-move</code></td><td>Coverage of market moves themselves: prices, flows</td></tr><tr><td><code>analysis-commentary</code></td><td>Analysis, outlooks, opinion (commentary, not an event)</td></tr><tr><td><code>ops-notice</code></td><td>Exchange or service operational notices (listings, maintenance)</td></tr><tr><td><code>data-point</code></td><td>A single data point or statistical observation</td></tr><tr><td><code>digest</code></td><td>Round-up coverage bundling several events</td></tr><tr><td><code>election</code></td><td>Elections and voting: primaries and results, candidacies, schedules and rules, polls</td></tr><tr><td><code>appointment</code></td><td>Appointments, nominations, resignations, dismissals, and successions to key posts</td></tr><tr><td><code>disaster</code></td><td>Natural disasters and extreme weather</td></tr><tr><td><code>diplomatic-event</code></td><td>Diplomatic processes between states: summits, negotiations, treaty signings, ceasefires</td></tr></tbody></table>