Skip to main content

​
The item

Hacker News has one content unit, an HnItem, and type says which kind it is: story or comment. Both carry an author, a timestamp and a link back to the discussion; a story additionally carries a score, a comment count and the URL it submitted. title is the story’s own title on a story, and the parent story’s title on a comment. That is what lets a comment tell you what it is a comment on without a second request. url is what the item submitted — the linked article on a story, and null on a comment and on an Ask HN post. hnUrl is always the discussion on news.ycombinator.com.

​
Coverage

A Watch on Hacker News requires a search term. There is no channel, subreddit or author to scope to, so a Watch without one would mean “everything on Hacker News”. The match runs over titles, submitted URLs and comment bodies. min_points filters on the score at the moment we read it, so it only narrows stories — comments carry no points. Interval: 120–86400 seconds. Cap: 20 active Watches per Account. Each tick costs 1 credit.

​
What an event carries

The first tick establishes a silent baseline and emits nothing. Later ticks emit hn_item.created with the full item. webhook_url is optional — without it the Watch still records every match, readable through GET /v1/hackernews/watches/{id}/events. See Webhooks.
A tick reads the newest matches and dedupes by id as well as by time, so an item that surfaces late still arrives exactly once.

​
Errors

A temporary Source failure is 503 and is not charged; the Watch reports it in its activity, readable through GET /v1/hackernews/watches/{id}/activity.