docs / hackernews

Hacker News

Stories, comments, users and full-text search.

base /hackernews/v17 endpoints

post/hackernews/v1/item1 credit

single item by id (story/comment/job/poll/pollopt) — all official fields + time_iso/kids_count/hn_url; hydrate_kids=resolve top-level comments

Parameter		Allowed / range	Description
id	required	—	HackerNews item id (story/comment/job/poll/pollopt) — the digits in an item URL (news.ycombinator.com/item?id=...).
hydrate_kids = false	optional	—	If true, resolve the item's top-level comments into full objects instead of bare ids.
kids_limit = 30	optional	1–100	When hydrate_kids=true, how many top-level comments to resolve (1-100).

Try in playground →

post/hackernews/v1/item_tree1 credit

full nested comment TREE for a story in ONE call; recursive children + descendants count

Parameter		Allowed / range	Description
id	required	—	HackerNews item id (story/comment/job/poll/pollopt) — the digits in an item URL (news.ycombinator.com/item?id=...).

Try in playground →

post/hackernews/v1/user1 credit

user profile by id: karma/created/about/submitted; hydrate_submitted=resolve recent submissions

Parameter		Allowed / range	Description
id	required	—	HackerNews username (case-sensitive), e.g. 'pg'.
hydrate_submitted = false	optional	—	If true, resolve the user's recent submissions into full objects instead of bare ids.
submitted_limit = 20	optional	1–100	When hydrate_submitted=true, how many recent submissions to resolve (1-100).

Try in playground →

post/hackernews/v1/stories2 credits

story-list (list=top/new/best/ask/show/job) → ranked hydrated stories; offset/limit pagination, hydrate=false for ids only

Parameter		Allowed / range	Description
list = top	optional	top · new · best · ask · show · job	Which HackerNews story list to return.
limit = 30	optional	1–100	Stories to return (1-100, default 30). Out-of-range values are clamped.
offset = 0	optional	0–500	Pagination offset into the story list (0-500). Skip N ranked stories.
hydrate = true	optional	—	If true, resolve each ranked story id into full objects instead of bare ids (default true).

Try in playground →

post/hackernews/v1/search1 credit

Full-text search: query + tags(story/comment/ask_hn/show_hn/poll/front_page/author_X/story_X) + min_points/max_points/min_comments/before/after + sort(relevance|date), paginated

Parameter		Allowed / range	Description
query	optional	—	Full-text search keywords. search needs query OR tags.
tags	optional	—	Tag filter. Built-ins: story, comment, ask_hn, show_hn, poll, front_page. Dynamic: author_USERNAME, story_ID. Comma-joins = AND, (a,b) = OR. search needs query OR tags.
sort = relevance	optional	relevance · date	Result ordering: relevance (default) or date (newest first). Any non-date value is treated as relevance.
page = 0	optional	0–50	0-based search results page (0-50). Page forward via meta.nbPages.
hits_per_page = 20	optional	1–100	Search results per page (1-100, default 20).
min_points	optional	0–	Minimum score (points) filter for search hits.
max_points	optional	0–	Maximum score (points) filter for search hits.
min_comments	optional	0–	Minimum comment-count filter for search hits.
max_comments	optional	0–	Maximum comment-count filter for search hits.
before	optional	—	Only hits created on/before this date. Accepts a unix timestamp or an ISO date (YYYY-MM-DD).
after	optional	—	Only hits created on/after this date. Accepts a unix timestamp or an ISO date (YYYY-MM-DD).
numeric_filters	optional	—	Advanced: raw Algolia numericFilters string, appended to the built min/max/date filters (e.g. 'points>100,created_at_i>1700000000').
restrict	optional	—	Advanced: restrictSearchableAttributes — limit matching to given Algolia fields (e.g. 'title' or 'title,story_text').

Try in playground →

post/hackernews/v1/updates1 credit

live changefeed: recently changed item ids + profiles + max_item; hydrate=resolve changed items

Parameter		Allowed / range	Description
hydrate = false	optional	—	If true, resolve the changed item ids into full objects instead of bare ids.
limit = 30	optional	1–100	Changed items to hydrate (1-100, default 30). Out-of-range values are clamped.

Try in playground →

post/hackernews/v1/max_item1 credit

the current largest item id on Hacker News — the newest id, useful for backfilling / id-range walks

Try in playground →

Example request · item

curl -X POST https://api.reefapi.com/hackernews/v1/item \
  -H "x-api-key: $REEF_KEY" \
  -H "content-type: application/json" \
  -d '{"id":8863}'

Response shape

{
  "ok": true,
  "data": { /* the result */ },
  "meta": {
    "latency_ms": 240,
    "record_count": 12,
    "completeness_pct": 100
  },
  "error": null
}