Helious News and feed API

openapi: 3.2.0
info:
  title: Helious Public News and feed API
  version: '2026-11-06'
  summary: Real-time US economic releases, Treasury auction results, rates and market news from the Helious desk.
  description: 'Read-only surface of api.helious.io. Every dataset here is first-party: captured by the Helious desk the moment it prints, with methodology at https://helious.io/methodology. On /v1/feed and the stream the Helious news wire rides beside the desk''s own posts: a wire headline is marked kind: headline and scored like everything else. The /v1 endpoints are the versioned contract for agents, and every tier sees the same endpoints and the same response shapes: only the history window, the delay and the market-data axis change, so an integration built keyless survives every upgrade untouched. The ladder: Sample (no key, no account, $0) gets 1 day of history, news and prints 1 hour behind, no market prices at all (price endpoints answer with the upgrade steps instead of numbers) and 30 calls a minute and 50 credits a month, shared by everyone on your network address. Free (a key on a free helious.io account, $0) gets 7 days of history, news 1 hour behind, every price board 60 minutes behind, and 60 calls a minute and 100 credits a month of your own. ONE CREDIT WALLET pays for everything an account does: a data call on any /v1 endpoint or MCP tool is 1 credit, a typed Ask Helious question in the terminal is 10, and on Free, Squawk and Starter the query fresh=1 (fresh: true as an MCP tool argument) answers that one call live for 5 credits. /v1/me, /v1/access, the MCP handshake, get_access_info, list_series, every error and every refusal are free; a keyless market wall is free too. Every answer carries X-Credits-Charged and X-Credits-Remaining headers and the same two numbers in meta (credits_charged, credits_left), and an empty wallet is a 429 with code out_of_credits carrying credits_left, resets_on, next_step (one sentence to relay), the packs that top it up (500 for $9.99, 1,500 for $24.99, never expiring) and upgrade_url: two ways on, a pack or a plan, and the person who owns the key chooses. Not on Pro and need one call live? Add fresh=1 to that request (fresh: true in an MCP tool''s arguments) and it answers live for 5 credits. Each delayed stream snapshot takes one credit on Free and with no key; a paid plan''s stream takes none. Starter ($14.99/mo or $135/yr) gets 12 months of history, live news and prints, every price board 60 minutes behind (live for 5 credits a call with fresh=1), 1,500 credits a month, at 90 calls a minute. Pro ($39.99/mo or $360/yr) gets 24 months of history, 3,000 credits a month and everything live for 1 credit (yields, treasuries, commodities, equities, FX, volatility, correlations) at 120 calls a minute, the streaming WebSocket included. Ultimate ($99/mo or $891/yr) gets 10 years of history, everything live, no credit cap, commercial use and redistribution, 300 calls a minute and the live stream on 5 connections a key. The stream at wss://api.helious.io/v1/stream is open on every tier, key or no key: below Pro it runs the delayed lane (one snapshot a minute, prices and the ranked NASDAQ-100 board 60 minutes behind, news on the plan''s own delay), and Pro and Ultimate run the live lane (every price tick, print and NASDAQ-100 update pushed the moment it happens, on up to 2 connections a key on Pro and 5 on Ultimate), in identical message shapes, so a stream integration survives the upgrade untouched. Authenticate with the same hel_ key sent as the ''Authorization: Bearer hel_...'' header, never a query parameter; the socket sends a hello whose mode field names your lane, feed items in the /v1/feed shape, price ticks, the ranked NASDAQ-100 board, daily official closes and the Helious momentum score, and answers ''ping'' with pong. Keys are sent as ''Authorization: Bearer hel_...''; GET /v1/access returns the ladder and the exact upgrade steps in plain words. There is also an MCP server at https://api.helious.io/mcp: point any MCP client at that URL and the same data arrives as tools.'
  x-stream: 'wss://api.helious.io/v1/stream is the live WebSocket, which OpenAPI cannot describe as a path. One socket on every plan: live on Pro (2 connections a key) and Ultimate (5), delayed below Pro (one snapshot a minute). Messages: hello (mode names the lane), feed (items in the /v1/feed shape; a release print is kind post, category release, with the actual, forecast, previous and sigma in its text), prices, ndx, market_data, score (the Helious momentum score when it moves, in the /v1/score shape), and pong to a ping. The hel_ key goes in the Authorization: Bearer header, never a query parameter; no key opens the delayed lane. Documented at https://helious.io/developers/#stream and https://helious.io/developers/economic-calendar-api/#stream.'
  contact:
    name: Helious support
    email: support@helious.news
    url: https://helious.io/contact
  termsOfService: https://helious.news/terms
servers:
- url: https://api.helious.io
tags:
- name: News and feed
  description: 'The Helious feed: the news wire and the desk''s own posts, each with a score for bonds and one for stocks.'
paths:
  /v1/feed:
    get:
      tags:
      - News and feed
      summary: 'The Helious feed: posts and wire headlines, with their scores'
      description: 'The Helious feed, newest first. Two kinds of item, told apart by `kind`. A post (kind post) is what Helious publishes: economic releases with their surprise, auction results, board updates, the daily brief, FOMC minutes and live squawk lines. A headline (kind headline) is a wire headline: breaking news, geopolitics, official statements, central bank speakers, bank and business notes. Every item has a stable id for duplicate detection and two score channels on a -10 to +10 scale: score and direction for bonds, equity_score and equity_direction for stocks. One story can be bullish for bonds and bearish for stocks (weak tech earnings: shares fall, money moves into Treasuries), so filter on the channel you trade. topic says what the item is about, and it is the code the Helious terminal prints on the row (equities, bonds, cb, geo, data, chatter); category says only which lane it came in on, so a stock story off the news wire has category news and topic equities. Most items carry helious_read, Helious''s plain-English line on why it matters. A headline also carries carried_at (when it crossed the Helious wire; created_at is the story''s own timestamp) and thread_id, a URL-free hash that stays the same when a story is retitled, so a collector can see one story twice. No headline carries a link or an image. Depth follows your plan: 1 day with no key, 7 days with a free account key, 12 months on Starter, 24 months on Pro, 10 years on Ultimate. That depth is the permanent posts (releases, auctions, desk posts, the brief, the minutes). Headlines are kept 7 days whatever the plan (official statements and Fed speakers 400 days), and so are squawk lines and the board lanes. Both kinds are delayed 60 minutes on the keyless and free tiers and live from Starter up: a post is held 60 minutes from created_at, a headline 60 minutes from the later of created_at and carried_at, so a headline is held at least a full hour from the moment it crossed the wire. q filters by word; categories narrows to chosen lanes (a category that does not exist is a 400 listing every name); kind narrows to headline or post; topics narrows to what items are about, matching the topic or the secondary topic (topics=equities finds every stock story, categories=equities only the equities lane). since moves the window''s start later (a date or an ISO 8601 time; never earlier than your plan''s depth, and meta.since says where the window started). q reads at most its first 8 distinct words. Every filter searches the whole window, and data.matched counts every match.'
      security:
      - {}
      - helious_key: []
      parameters:
      - name: q
        in: query
        required: false
        schema:
          type: string
      - name: categories
        in: query
        required: false
        description: 'Comma-separated lanes. Post lanes: release, auction, desk, brief, narrative, volboard, corr, fx, hormuz, squawk, live_event, minutes. Headline lanes: news, geo, bank, official, fed_speak, equities. Empty means all.'
        schema:
          type: string
        example: release,auction
      - name: kind
        in: query
        required: false
        description: headline for the wire headlines, post for the posts the desk writes. Empty means both.
        schema:
          type: string
          enum:
          - headline
          - post
        example: headline
      - name: topics
        in: query
        required: false
        description: 'Comma-separated topics: what an item is about, the code the Helious terminal prints on the row. equities (EQ), bonds (BONDS), cb (central banks), geo (geopolitics), data (macro prints), chatter (political and market voices), desk and narrative (Helious''s own cards), and energy and fx, which are only ever a secondary topic. An item matches on its topic or its secondary topic, as the terminal''s tabs do: bonds also finds a Fed story whose secondary topic is bonds. A topic that does not exist is a 400 listing every name. Empty means all.'
        schema:
          type: string
        example: equities
      - name: since
        in: query
        required: false
        description: Only items published at or after this date or ISO 8601 time (created_at). A time with no offset is read as UTC. It can move the window's start later, never earlier than your plan's history depth; meta.since says where the window started. When it asks for more than your plan holds and older items exist, meta.clamped is true and plan_limit says what a deeper plan reaches; when no plan reads further back than your window already does, meta.clamped is false and record_start says the first day any plan reads. Empty, or a value that is not a date or time, means the whole window, as on every /v1 endpoint that takes since.
        schema:
          type: string
        example: '2026-10-30T00:00:00Z'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 30
          maximum: 100
      - $ref: '#/components/parameters/fresh'
      responses:
        '200':
          description: summary + source + data + meta envelope. data.items is a list of FeedItem, newest first; data.matched is the window total and data.shown the page size; data.tape_heartbeat is the newest ingest time across every lane, so a quiet feed can be told from a dead pipeline.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - type: object
                  properties:
                    data:
                      type: object
                      properties:
                        items:
                          type: array
                          items:
                            $ref: '#/components/schemas/FeedItem'
                        shown:
                          type: integer
                        matched:
                          type: integer
                        tape_heartbeat:
                          type: string
                          format: date-time
              example:
                summary: '2 items in the Helious feed since 2026-10-24: on this page, 1 wire headline and 1 desk post. Newest headline: "U.S. stock futures sink, Nasdaq down 2% as Amazon, Intel earnings underwhelm" at 30 Oct 2026 01:31 UTC.'
                source:
                  name: Helious
                  url: https://helious.io/news
                  cite_as: Helious, https://helious.io/news
                  attribution: 'Data: Helious (helious.io)'
                  live: This is live data on your plan.
                data:
                  items:
                  - id: 9783ea914ba4193bb48d9e12c1c9c57a
                    kind: headline
                    title: U.S. stock futures sink, Nasdaq down 2% as Amazon, Intel earnings underwhelm
                    category: news
                    created_at: '2026-10-30T01:31:14+00:00'
                    carried_at: '2026-10-30T01:31:26+00:00'
                    score: 2.0
                    direction: BULLISH BONDS
                    equity_score: -6.0
                    equity_direction: BEARISH EQUITIES
                    topic: equities
                    helious_read: Weak tech earnings drag shares down, and money tends to drift toward safer government bonds when stocks fall.
                    thread_id: 70be1f9b327719da
                  - id: auc-912797WG8-2026-10-22
                    kind: post
                    title: '8-Week (2-month) Bill auction: IN LINE'
                    text: $105B on offer, B/C 2.57 (avg 2.71), high 4.015%, indirect 57.8% (avg 60.2), direct 5.5% (avg 6.0), dealer 36.7% (avg 33.8). IN LINE demand, no directional read for bonds.
                    category: auction
                    created_at: '2026-10-22T15:33:57+00:00'
                    score: -1.12
                    direction: NEUTRAL
                    equity_score: 0.0
                    equity_direction: NEUTRAL
                    topic: bonds
                    helious_read: Cover a touch below average on a bill, nothing for the curve.
                    url: https://helious.io/news/auc-912797WG8-2026-10-22/8-week-2-month-bill-auction-in-line
                  shown: 2
                  matched: 2
                  tape_heartbeat: '2026-10-25T10:32:27+00:00'
                meta:
                  tier: pro
                  history_days: 730
                  delay_sec: 0
                  since: '2026-10-24'
                  categories:
                  - auction
                  - news
                  credits_charged: 1
                  credits_left: 2999
        '429':
          description: 'Over the per-minute limit (code rate_limited, Retry-After the rest of the minute) or the wallet cannot pay (code out_of_credits: credits_left, resets_on, retry_after_seconds, packs, topup_url, upgrade_url, and fresh_costs on a held plan). Nothing is charged for a refusal.'
      operationId: getV1Feed
      x-operation-id-source: derived
  /api/news/index:
    get:
      tags:
      - News and feed
      summary: Indexable posts, newest first
      description: Paginated index of first-party posts (releases, auction recaps, daily briefs). Article pages render at https://helious.io/news/{id}.
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
      - name: per
        in: query
        required: false
        schema:
          type: integer
          default: 40
          maximum: 100
      - name: tab
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Post index
          content:
            application/json:
              schema:
                type: object
      operationId: getApiNewsIndex
      x-operation-id-source: derived
  /api/article/{item_id}:
    get:
      tags:
      - News and feed
      summary: One post with its full analysis
      description: A single post (release stats, auction breakdown or note) plus related posts. The canonical page is https://helious.io/news/{id}.
      parameters:
      - name: item_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Article
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Unknown or expired id
      operationId: getApiArticleByItemId
      x-operation-id-source: derived
  /api/seo/feed.xml:
    get:
      tags:
      - News and feed
      summary: RSS feed of the newest posts
      description: Also served at https://helious.io/feed.xml.
      responses:
        '200':
          description: RSS 2.0
          content:
            application/rss+xml:
              schema:
                type: string
      operationId: getApiSeoFeedXml
      x-operation-id-source: derived
components:
  schemas:
    FeedItem:
      type: object
      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.'
      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
          nullable: true
          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
          nullable: true
          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.'
    Envelope:
      type: object
      description: Every /v1 response. `summary` states the answer as one plain-English sentence and `source` says who to credit for it, both before the raw `data`, so the finished claim is the first thing a reader meets.
      properties:
        summary:
          type: string
          description: The answer as a sentence, with the numbers in it. Identical to the sentence the matching MCP tool returns.
        source:
          type: object
          description: Who to credit and where a reader can check the number.
          properties:
            name:
              type: string
              example: Helious
            url:
              type: string
              format: uri
              description: The Helious page backing this answer.
            cite_as:
              type: string
              example: Helious, https://helious.io/auctions
            attribution:
              type: string
            live:
              type: string
              description: How current these numbers are on YOUR plan, and how to ask for them again. Says the data is live only on a tier that serves it live.
        data:
          type: object
          description: The dataset itself.
        meta:
          type: object
          description: When it was true, and what your plan allows.
        plan_limit:
          type: object
          description: Present only when your plan moved the window AND Helious holds rows older than it. Says this is a plan limit rather than missing data, where the record begins (record_begins, on the lanes that say it), the plans that reach further, and the exact step to relay to the person you work for.
        record_start:
          type: object
          description: 'Present instead of plan_limit when you asked for more history than any plan reads here: record_begins is the first day any plan reads (null when there is none yet), your plan''s window already reaches it, older_rows_on_any_plan is false, and meta.clamped is false. No plan reaches further back, so there is nothing to upgrade for.'
  parameters:
    fresh:
      name: fresh
      in: query
      required: false
      schema:
        type: boolean
      description: 'Not on Pro or Ultimate? Add fresh=1 to this request and this one call answers live (news, prints, auctions, boards and prices at the live instant) for 5 credits. Left out, Free, Squawk and Starter get the answer 60 minutes behind for 1 credit. With fewer than 5 credits left the live call is refused with out_of_credits and nothing is charged; the same call without the flag still answers for 1. Accepted and free on Pro and Ultimate, where the view is already live. Ignored without a key: a free account key has the flag. Over MCP the same flag is fresh: true in the tool''s arguments.'
  securitySchemes:
    helious_key:
      type: http
      scheme: bearer
      description: 'Your Helious API key, like hel_xxx, made on your helious.io account page (Account, then API keys). Every /v1 endpoint also works with no key at the sample tier: 1 day of history, news 1 hour behind, no market prices. A free account key gets 7 days and a rate budget of your own. Starter ($14.99/mo) takes the news live, reaches 12 months back and adds the Treasury curve 60 minutes behind; Pro ($39.99/mo) makes every price live with 24 months of history, the /v1/stream WebSocket included; Ultimate ($99/mo) reaches 10 years, allows commercial use and holds the live stream on 5 connections a key (Pro holds 2).'
    helious_oauth:
      type: oauth2
      description: Sign the person in instead of asking them for a key. Dynamic client registration is open, so your client can enrol itself; the one human step is the consent screen. Access tokens last an hour; ask for offline_access to get a rotating refresh token. Full details at https://helious.io/auth.md.
      flows:
        authorizationCode:
          authorizationUrl: https://helious.io/oauth/authorize
          tokenUrl: https://api.helious.io/oauth/token
          refreshUrl: https://api.helious.io/oauth/token
          scopes:
            market:read: Read Helious market data at that plan level.
            account:read: See which plan the account is on.
            openid: Confirm the account identity to your app.
            offline_access: Get a refresh token so you stay connected.