> 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. An opinion piece, an analysis or explainer, and a roundup of several items carry a genre label at the start of the headline: <code>Opinion:</code>, <code>Analysis:</code> or <code>Roundup:</code>, translated in each language. Match on the prefix when you want to tag a genre or leave it out</td></tr><tr><td><code>sourceHeadline</code></td><td>string</td><td>The original outlet's headline, as published. It belongs to the outlet: use it as the title of the link to the original article, together with that link</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="#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 link-preview (OG) image. It belongs to the outlet: hotlink it together with the link to the original article, the way a link preview does. See <a href="/docs/resources/news-licensing.md">News Licensing</a></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. The 59 slugs, the filtering rules, and a call for each slug 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   | 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  | Wall Street Journal |
| 20  | New York Times      |
| 21  | AP News             |
| 22  | Fox News            |
| 23  | CBS News            |
| 24  | NBC News            |
| 25  | Washington Post     |
| 26  | CNN                 |
| 27  | Guardian            |
| 28  | Forbes              |
| 29  | Fortune             |
| 30  | Benzinga            |
| 31  | MS NOW              |
| 32  | BBC                 |
| 33  | Foreign Policy      |
| 34  | U.S. SEC            |
| 35  | CFTC                |
| 36  | OFAC                |
| 37  | IMF                 |
| 38  | Federal Reserve     |
| 39  | FDIC                |
| 40  | White House         |
| 41  | ABC News            |
| 42  | Economist           |
| 43  | NPR                 |
| 44  | TechCrunch          |
| 45  | DW                  |
| 46  | France 24           |
| 47  | Odaily              |
| 48  | CryptoRank          |
| 49  | SCMP                |

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