FeedItem

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/helious-io/json-schema/helious-io-feed-item-schema.json",
  "title": "FeedItem",
  "description": "One item of the Helious feed, on /v1/feed, in every {type: 'feed'} message on /v1/stream and from the MCP get_feed tool. `kind` says what it is: a desk post, or a wire headline. Every item is read on two channels, bonds (score, direction) and stocks (equity_score, equity_direction), and filed under a topic. On the live stream (Pro and Ultimate), an item Helious changes after it first lands (a later read, a body filled in) is sent again with the same id in a message marked refresh: true; keep the newer copy. A headline never carries a link or an image. Keys absent from an item are not null, they are left out: a headline with no body has no text, a post that is not a page has no url.",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/helious-io-openapi.json#/components/schemas/FeedItem",
  "type": "object",
  "required": [
    "id",
    "kind",
    "title",
    "category",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Stable identifier. The same story keeps its id through a retitle, so dedupe on it."
    },
    "kind": {
      "type": "string",
      "enum": [
        "headline",
        "post"
      ],
      "description": "headline: a wire headline. post: a post the desk wrote."
    },
    "title": {
      "type": "string",
      "description": "The headline, or the post's title."
    },
    "text": {
      "type": "string",
      "description": "The body. On a post, the post as Helious wrote it. On a headline, the body text alone, without the headline repeated; absent when a headline has no body."
    },
    "category": {
      "type": "string",
      "description": "The lane the item came in on, not what it is about (that is topic). Post lanes: release, auction, desk, brief, narrative, volboard, corr, fx, hormuz, squawk, live_event, minutes. Headline lanes: news (breaking and business), geo (geopolitics), bank (bank and market notes), official (official statements and central bank press), fed_speak (Fed speakers), equities (the equity wires). Most stock stories arrive on news, so filter on topic to find them."
    },
    "topic": {
      "type": "string",
      "enum": [
        "equities",
        "bonds",
        "cb",
        "geo",
        "data",
        "chatter",
        "desk",
        "narrative"
      ],
      "description": "What the item is about: the code the Helious terminal prints on the row. equities (EQ: single names, indices, earnings), bonds (BONDS: yields, auctions, credit), cb (central bank talk and decisions), geo (geopolitics), data (macro prints), chatter (political and market voices), desk and narrative (Helious's own cards). Absent on the rare item with no topic."
    },
    "secondary_topic": {
      "type": "string",
      "enum": [
        "bonds",
        "energy",
        "fx"
      ],
      "description": "Where the item also belongs, when it does: bonds on a central bank, geopolitics or data story with a rates read (the terminal's BONDS tab shows it too), energy on an oil or gas line, fx on a currency line. Never the same as topic."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "When the item was published, ISO 8601 UTC. On a post, when Helious published it, and the clock its 60-minute hold runs on below Starter. On a headline, the publication stamp the wire sent."
    },
    "carried_at": {
      "type": "string",
      "format": "date-time",
      "description": "Headlines only. When the headline crossed the Helious wire, ISO 8601 UTC. created_at is the story's own timestamp; a collector ordering by arrival uses carried_at. Below Starter a headline is held 60 minutes from the later of created_at and carried_at."
    },
    "score": {
      "type": [
        "number",
        "null"
      ],
      "description": "The bond channel, -10 to +10: positive is bullish for government bonds (prices up, yields down), negative is bearish, zero is no read. The Helious terminal shows whichever channel your book follows, so its row can show the equity_score instead."
    },
    "direction": {
      "type": "string",
      "description": "The bond channel as a phrase: BULLISH BONDS, BEARISH BONDS or NEUTRAL. On a headline or a squawk line it is read from score: BULLISH BONDS above +1, BEARISH BONDS below -1, otherwise NEUTRAL. A post carries its own call: a release by the sign of score, naming its own government bond when it is from outside the US (BULLISH BUNDS, BEARISH GILTS, BULLISH JGBS), and an auction by its demand verdict. Match the whole string."
    },
    "equity_score": {
      "type": [
        "number",
        "null"
      ],
      "description": "The stock channel, -10 to +10, from the same read as score: positive is bullish for equities, negative bearish, zero no read. A story can be bearish here and bullish on score at once, as when weak earnings send money from stocks into bonds."
    },
    "equity_direction": {
      "type": "string",
      "enum": [
        "BULLISH EQUITIES",
        "BEARISH EQUITIES",
        "NEUTRAL"
      ],
      "description": "The stock channel as a phrase, by the rule the item's bond label follows. On a release: BULLISH EQUITIES when equity_score is above zero, BEARISH EQUITIES below zero, as the release card itself reads. On every other item: BULLISH EQUITIES above +1, BEARISH EQUITIES below -1, otherwise NEUTRAL. Present whenever equity_score is a number."
    },
    "helious_read": {
      "type": "string",
      "description": "Helious's plain-English line on why the item matters. Present when Helious has read it."
    },
    "digest": {
      "type": "object",
      "description": "On FOMC minutes and central bank speeches: Helious's read of the full document (summary, what is new, key findings, committee lean, verified quotes)."
    },
    "thread_id": {
      "type": "string",
      "description": "Headlines only. A 16-character hash of the story behind the headline, the same across a retitle and across the hours a liveblog keeps one address. It cannot be turned back into an address; Helious never serves the address."
    },
    "url": {
      "type": "string",
      "format": "uri",
      "description": "Posts only, and only those with a permanent page: the Helious page for this post. Never present on a headline."
    }
  }
}