> 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 news-serving endpoint (`/v1/news`, `/v1/top-news`, `/v1/match`) returns items with this schema. A news item has three groups of fields.

<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> <code>whyItMatters</code></td></tr><tr><td><h4><i class="fa-brain" style="color:$primary;">:brain:</i></h4></td><td><strong>Intelligence</strong><br>How the market reads it</td><td><code>impact</code> <code>impactScore</code> <code>sentiment</code> <code>eventType</code> <code>clusterId</code> <code>relatedCount</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>sourceImageUrl</code> <code>entities</code> <code>categories</code> <code>coins</code> <code>covers</code></td></tr></tbody></table>

<figure><img src="/files/Nsyb682gZvCRA84XHPDl" alt="How the fields render in a real feed"><figcaption><p>How the fields render: headline, impact dots, sentiment, source, cover</p></figcaption></figure>

## Schema

| Field            | Type           | Description                                                                                                                                                                                               |
| ---------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`             | string         | Unique news ID. Stable and permanent: an item's id never changes                                                                                                                                          |
| `headline`       | string         | Rewritten headline                                                                                                                                                                                        |
| `summary`        | string         | Short summary                                                                                                                                                                                             |
| `body`           | string         | Key-point body (fact based)                                                                                                                                                                               |
| `whyItMatters`   | string \| null | Why this matters. AI-inferred. Present only for impact 4 and 5, and may still be null. Always handle null                                                                                                 |
| `impact`         | number         | 2 to 5, higher = more important. Equals the dots on FLASH surfaces (●●●●○ = 4)                                                                                                                            |
| `sentiment`      | string \| null | `Bullish`, `Mildly Bullish`, `Neutral`, `Mildly Bearish`, `Bearish`. Always `null` for politics and geopolitics (neutrality by design, not missing data)                                                  |
| `eventType`      | string         | One of 18 types. Full table below                                                                                                                                                                         |
| `impactScore`    | number         | 0 to 100. Fine-grained importance under `impact`: use it to sort within a tier                                                                                                                            |
| `entities[]`     | array          | `{ name, aliases[], ticker }`. `name` = the entity's full name ("Federal Reserve"), `aliases` = other spellings it goes by ("Fed"), `ticker` = ticker symbol ("BTC"; null for non-assets). Always English |
| `source`         | object         | Original outlet: `{ name, logoUrl }`. `logoUrl` is the outlet's logo                                                                                                                                      |
| `sourceUrl`      | string         | Link to the original article                                                                                                                                                                              |
| `publishedAt`    | string         | ISO 8601 UTC                                                                                                                                                                                              |
| `clusterId`      | string \| null | Same event = same cluster. null when the article is not clustered                                                                                                                                         |
| `relatedCount`   | number         | How many articles relate to this event. Render as "+N more reports". **Omitted when `clusterId` is null**                                                                                                 |
| `covers[]`       | array          | Cover image `{ url, width, height }`. Single 1750x1000 rendition, produced and licensed by FLASH                                                                                                          |
| `sourceImageUrl` | string \| null | The original article's OG image, hotlinked. Rights remain with the outlet                                                                                                                                 |
| `categories[]`   | array          | The categories this article belongs to (can be more than one for cross-category stories)                                                                                                                  |
| `coins[]`        | array          | `{ cmcId, name, symbol }`. Crypto articles only, otherwise `[]`. `cmcId` is the CoinMarketCap ID, so you can join or deep-link to your own asset pages without ticker ambiguity                           |
| `lang`           | string         | Language of this rendition                                                                                                                                                                                |

{% hint style="warning" %}
**Three nulls to handle.** `whyItMatters` can be null even at impact 4 and 5. `sentiment` is always null on politics and geopolitics items. `relatedCount` is omitted entirely when `clusterId` is null.
{% 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="/files/6K1QqMSnW67skuQmg8TA" alt="The impact scale"><figcaption></figcaption></figure>

## sentiment

`sentiment` answers how the market reads the event, in five values. Mildly means lower intensity.

<figure><img src="/files/HexrJxp22H0KPYv9DXw6" alt="The five sentiment values"><figcaption></figcaption></figure>

## 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. Render `relatedCount` as "+N more reports".

<figure><img src="/files/5MhffQFrQWPTXlbh6sDk" alt="Many reports converge into one item"><figcaption></figcaption></figure>

## eventType values (18)

| Family                  | eventType                                              |
| ----------------------- | ------------------------------------------------------ |
| Policy, regulation, law | `policy-decision`, `regulation-action`, `legal-action` |
| Elections, appointments | `election`, `appointment`                              |
| Data                    | `data-release`, `data-point`                           |
| Corporate, funding      | `corporate-action`, `funding-deal`                     |
| Security                | `security-incident`                                    |
| Disaster                | `disaster`                                             |
| Geopolitics, diplomacy  | `geopolitical-event`, `diplomatic-event`               |
| Statements, commentary  | `official-statement`, `analysis-commentary`            |
| Market, operations      | `market-move`, `ops-notice`, `digest`                  |

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