Hacker News front page and comment threads as JSON, ranked and flattened

Hacker News has a clean official API, and it is the right tool for building a client. It is the wrong tool for “give me the front page with points and comment counts right now”, because that is 31 requests, and for “give me this thread”, because that is one request per comment. These two endpoints read the rendered page instead and return it in one shape.

Front page

curl "https://api.webscrapingapi.dev/v1/structured/hackernews/front?page=1" \
  -H "X-API-Key: wsa_your_key"

page is optional and 1-based. The answer is the stories on that page, in the order the site prints them.

{
  "site": "hackernews",
  "action": "front",
  "data": {
    "count": 30,
    "stories": [
      {
        "id": 45312001,
        "rank": 1,
        "title": "Samsung is expected to more than double its HBM output",
        "url": "https://example-news.com/samsung-hbm",
        "site": "example-news.com",
        "points": 125,
        "author": "someone",
        "commentCount": 84,
        "age": "3 hours ago"
      }
    ]
  },
  "source": "live",
  "age": 0,
  "credits": 1
}

url is the story link; for Ask HN and other self posts it points at the item page itself. site is the hostname the page shows in parentheses, or null for self posts. age is the relative time as printed, because that is what the page carries; if you need a timestamp, the item id is monotonic and the official API has the exact time.

One thread

curl "https://api.webscrapingapi.dev/v1/structured/hackernews/item?id=1" \
  -H "X-API-Key: wsa_your_key"

{
  "site": "hackernews",
  "action": "item",
  "data": {
    "id": 1,
    "title": "Y Combinator",
    "url": "http://ycombinator.com",
    "points": 61,
    "author": "pg",
    "age": "on Oct 9, 2006",
    "comments": [
      { "id": 15, "author": "sama", "age": "on Oct 9, 2006", "depth": 0, "text": "…" },
      { "id": 17, "author": "pg", "age": "on Oct 9, 2006", "depth": 1, "text": "…" }
    ]
  },
  "source": "cache",
  "age": 240,
  "credits": 0
}

Comments come back flat, in page order, with depth. A reply to a top-level comment has depth: 1, a reply to that has depth: 2, and so on. Rebuilding the tree is a ten-line loop; reading it flat is what most summarisers want anyway. text is plain text with paragraph breaks kept and HTML removed.

Freshness

The front page changes every few minutes, so both endpoints store answers for only 10 minutes. Within that window every caller gets the stored copy for 0 credits; after it, the next caller fetches a fresh page for 1 credit and everyone shares that. Pass max_age=0 to force a fetch, or a larger value if ten-minute-old rankings are fine for your use.

What to build with it

A daily digest that lists the top stories and their discussion size is one request. A “summarise this thread” tool is one request plus a model call. A monitor that watches for a domain to appear on the front page is one request every ten minutes, stored and shared with everyone else running the same monitor. The reference page has the full parameter list.